PaySwarm Vocabulary

Unofficial Draft 13 December 2011

Editor:
Manu Sporny, Digital Bazaar, Inc.

Abstract

Status of This Document

This document is merely a public working draft of a potential specification. It has no official standing of any kind and does not represent the support or consensus of any standards organisation.

Table of Contents

1. Introduction

This document describes a number of classes and properties that can be used to express digital sales, rentals, contracts, licenses and micropayment-based exchanges on the Semantic Web. These include things such as micropayments for blog articles, video rentals, electronic magazine subscriptions, data vending, provisioning of web services under legally enforceable contracts, and other novel business models that are powered by micropayments and the Web. This vocabulary is a part of the PaySwarm Universal Web Payments Specification.

2. Classes

2.1 Asset

An asset describes a particular item that is provided as a part of a commercial transaction. It is usually an item that can be accessed or acquired on the basis of a sale or rental under the terms of a particular license. Examples of assets include web pages, music files, video streams, use of virtual machines by the hour, 3D printer files for on-demand manufacturing, radio spectrum and many other items that are capable of being transacted.

Status
unstable
Parent Class
owl:Thing
Properties
dc:title, dc:creator, ps:contentUrl, ps:assetProvider, ps:authority, ps:validFrom, ps:validUntil, ps:signature

The following example describes a web page asset with the title "PaySwarm in Practice - Full Article #1". The article was created by "Digital Bazaar, Inc." and the information in the asset is valid from November 28th, 2010 to November 28th, 2011. The asset is digitally signed by the person providing it and thus can be cached, stored and then presented to someone else in a manner that is verifiable by the receiving party.

{
   "@subject": "https://example.org/articles/1#asset",
   "@type": ["ps:Asset", "ps:WebPage"],
   "dc:title": "PaySwarm in Practice",
   "dc:creator": 
   {
      "foaf:name": "Digital Bazaar, Inc.",
   }
   "ps:contentUrl": "https://example.org/articles/1",
   "ps:assetProvider": "https://example.org/person/john-doe#me",
   "ps:authority": "https://payswarm.example.com/about#authority",
   "ps:validFrom": "2010-11-28T00:00:00Z",
   "ps:validUntil": "2011-11-28T00:00:00Z"
   "ps:signature": 
   {
       "@type": "sig:JsonLdSignature",
       "sig:signer": "https://payswarm.example.com/people/john-doe#key-5",
       "sig:signatureValue": "OWM3YzI4OGQzNGVkMzV...IyZTk2MzQzNmExMgo="
   }
}
        

2.2 Contract

A contract is the result of a commercial transaction in PaySwarm and contains information such as the Listing, the Asset that was purchased, the parties involved in the transaction, the License outlining the rights to the Asset, and payment information associated with the transaction.

Status
unstable
Parent Class
com:Transaction
Properties
com:amount, com:currency, com:date, com:payee, com:transfer, dc:created, ps:asset, ps:assetProvider, ps:assetAcquirer, ps:assetProviderIdentity, ps:license, ps:listing, ps:signature

The following example describes a purchase that occurred on March 2nd 2011 for a Web-based article called "PaySwarm in Practice". The article was authored and listed for sale by Bob Smith and a personal use license was acquired by Jane, who may now peruse the article.

{
   "@subject": "http://payswarm.example.com/contracts/28394729347",
   "@type": ["ps:Transaction", "ps:Contract"],
   "com:amount": "0.05",
   "com:currency": "USD",
   "com:date": "2011-03-02T03:00:53Z",
   "com:payee": 
   [
      {
         "@type": "com:Payee",
         "com:currency": "USD",
         "com:destination": "https://payswarm.example.com/i/authority/accounts/main",
         "com:payeePosition": 0,
         "com:rate": "10.00",
         "com:rateContext": "com:TaxExempt",
         "com:rateType": "com:InclusivePercentage",
         "rdfs:comment": "PaySwarm Authority Transaction Processing"
      }
   ],
   "com:transfer": 
   [
      {
         "@type": "com:Transfer",
         "com:amount": "0.045",
         "com:currency": "USD",
         "com:destination": "https://payswarm.example.com/i/bob/accounts/primary",
         "com:forTransaction": "http://payswarm.example.com/contracts/28394729347",
         "com:source": "https://payswarm.example.com/i/jane/accounts/primary",
         "rdfs:comment": "Payment for PaySwarm in Practice by Bob Smith."
      },
      {
         "@type": "com:Transfer",
         "com:amount": "0.005",
         "com:currency": "USD",
         "com:destination": "https://payswarm.example.com/i/authority/accounts/main",
         "com:forTransaction": "http://payswarm.example.com/contracts/28394729347",
         "com:source": "https://payswarm.example.com/i/jane/accounts/primary",
         "rdfs:comment": "PaySwarm Authority Transaction Processing"
      }
   ],
   "dc:created": "2011-03-02T03:00:53Z",
   "ps:asset": 
   {
      "@subject": "http://example.com/articles/1#asset",
      "@type": ["ps:Asset", "ps:WebPage"],
      "dc:creator": 
      {
         "foaf:name": "Bob Smith"
      },
      "dc:title": "PaySwarm in Practice",
      "ps:assetProvider": "https://payswarm.example.com/i/bob",
      "ps:authority": "https://payswarm.example.com/client-config",
      "ps:contentUrl": "http://example.com/articles/1",
      "ps:signature": 
      {
         "@type": "ps:JsonLdSignature",
         "dc:created": "2011-03-02T00:00:00Z",
         "dc:creator": "https://payswarm.example.com/i/bob/keys/4",
         "ps:signatureValue": "XuLEGuq+ne56Qsc5Nic8I="
      }
   },
   "ps:assetAcquirer": "https://payswarm.example.com/i/jane",
   "ps:assetProviderIdentity": 
   {
      "ps:identityHash": "df913752be56fe0d37dcedc2d7f44708373d2a68"
   },
   "ps:license": 
   {
      "@subject": "http://payswarm.example.com/licenses/blogging",
      "@type": "ps:License",
      "dc:format": "text/html",
      "ps:licenseTemplate": "Personal Use License ..."
   },
   "ps:listing": 
   {
      "@subject": "http://example.com/articles/1#listing",
      "@type": ["gr:Offering", "ps:Listing"],
      "com:payee": 
      [
         {
            "@subject": "http://example.com/articles/1#listing-payee",
            "@type": "com:Payee",
            "com:currency": "USD",
            "com:destination": "https://payswarm.example.com/i/bob/accounts/primary",
            "com:rate": "0.05",
            "com:rateType": "com:FlatAmount",
            "rdfs:comment": "Payment for PaySwarm in Practice by Digital Bazaar."
         }
      ],
      "com:payeeRule": 
      [
         {
            "@type": "com:PayeeRule",
            "com:destinationOwnerType": "ps:Authority",
            "com:maximumRate": "10",
            "com:rateType": "com:InclusivePercentage"
         }
      ],
      "ps:asset": "http://example.com/articles/1#asset",
      "ps:assetHash": "14618b56ff597a2fed560db9aa0610fe442106a4",
      "ps:license": "http://payswarm.example.com/licenses/blogging",
      "ps:licenseHash": "0d8866836917f8ef58af44accb6efab9a10610ad",
      "ps:signature": 
      {
         "@type": "ps:JsonLdSignature",
         "dc:created": "2011-03-02T00:00:00Z",
         "dc:creator": "https://payswarm.example.com/i/bob/keys/4",
         "ps:signatureValue": "KXtwA5kXZBJzj1rkPMJmGDROjM+fpi2cJIB+Xqf10="
      },
      "ps:validFrom": "2011-03-02T00:00:00+0000",
      "ps:validUntil": "2011-03-03T00:00:00+0000"
   },
   "ps:listingHash": "1acbd23c3a7d8827270a959a2760f7c4ded98022",
   "ps:signature": 
   {
      "@type": "ps:JsonLdSignature",
      "dc:created": "2011-03-02T03:00:53Z",
      "dc:creator": "https://payswarm.example.com/i/authority/keys/1",
      "ps:signatureValue": "ZnGaAs0QCIfEAvCsj2TxRTs8ekQrbbQUXvTLWcQ0kQ=="
   }
}
        

2.3 Data

The Data class is typically found as a decorator class for an Asset. That is, the Data class is usually found as an rdf:type descriptor attached to an Asset. Data is used to specify that the asset is a pre-recorded or live stream of bytes.

Status
unstable
Parent Class
owl:Thing
Properties
dc:title, dc:creator, ps:contentUrl, ps:assetProvider, ps:authority, ps:validFrom, ps:validUntil, ps:signature

The following example shows an Data Asset for a byte stream for sale that is a video with the title "Learning How Cells Divide" by John Doe.

{
   "@subject": "http://example.com/videos#cell-division",
   "@type": ["ps:Asset", "ps:Data"],
   "dc:creator": 
   {
      "foaf:name": "John Doe"
   },
   "dc:title": "Learning How Cells Divide",
   "ps:assetProvider": "https://payswarm.example.com/i/john",
   "ps:authority": "https://payswarm.example.com/client-config",
   "ps:contentUrl": "http://example.com/video/cell-division.mpg",
   "ps:signature": 
   {
      "@type": "ps:JsonLdSignature",
      "dc:created": "2011-03-12T00:00:00Z",
      "dc:creator": "https://payswarm.example.com/i/john/keys/2",
      "ps:signatureValue": "ne56Qsc5IXuLEGuq+Nic8="
   }
}
        

2.4 License

A license is a legal description of a licensee's rights to a particular Asset. Licenses are usually included as a part of a contract to express what a buyer may do with the asset that has been purchased.

Status
unstable
Parent Class
owl:Thing
Properties
dc:format, ps:licenseTemplate, ps:licenseTerms

The following example describes an overly-simplified personal use license.

{
   "@subject": "http://payswarm.example.com/licenses/personal-use",
   "@type": "ps:License",
   "dc:format": "text/html",
   "ps:licenseTemplate": "This personal use license allows you to save the 
      purchased item onto any device that you own for your personal enjoyment
      and make up to <span property=\"ex:physicalCopies\" /> printed
      copies of the work for personal use."
   "ps:licenseTerms": 
   {
      "ex:physicalCopies": 5
   }
}
        

2.5 Listing

A Listing describes the combination of an Asset that is for sale under a specific License and a set of payment terms that must be fulfilled in order to access the Asset. Listings are often published on websites that sell assets via PaySwarm as a way to express wares for sale in a decentralized manner.

Status
unstable
Parent Class
owl:Thing
Properties
com:payee, com:payeeRule, ps:asset, ps:assetHash, ps:license, ps:licenseHash, ps:signature, ps:validFrom, ps:validUntil

The following example describes an asset for sale for $0.05 USD under a license that covers acceptable use of blog posts. The offer is valid from March 2nd 2011 to March 3rd 2011. The only restriction on additional payees is that the PaySwarm Authority (the organization processing the payment) may only take a maximum of 10% of the final sale price to cover their fees.

{
   "@subject": "http://example.com/articles/1#listing",
   "@type": ["gr:Offering", "ps:Listing"],
   "com:payee": 
   [
      {
         "@subject": "http://example.com/articles/1#listing-payee",
         "@type": "com:Payee",
         "com:currency": "USD",
         "com:destination": "https://payswarm.example.com/i/bob/accounts/primary",
         "com:rate": "0.05",
         "com:rateType": "com:FlatAmount",
         "rdfs:comment": "Payment for PaySwarm in Practice by Digital Bazaar."
      }
   ],
   "com:payeeRule": 
   [
      {
         "@type": "com:PayeeRule",
         "com:destinationOwnerType": "ps:Authority",
         "com:maximumRate": "10",
         "com:rateType": "com:InclusivePercentage"
      }
   ],
   "ps:asset": "http://example.com/articles/1#asset",
   "ps:assetHash": "14618b56ff597a2fed560db9aa0610fe442106a4",
   "ps:assetProvider": "https://payswarm.example.com/i/bob",
   "ps:license": "http://payswarm.example.com/licenses/blogging",
   "ps:licenseHash": "0d8866836917f8ef58af44accb6efab9a10610ad",
   "ps:signature": 
   {
      "@type": "ps:JsonLdSignature",
      "dc:created": "2011-03-02T00:00:00Z",
      "dc:creator": "https://payswarm.example.com/i/bob/keys/4",
      "ps:signatureValue": "KXtwA5kXZBJzj1rkPMJmGDROjM+fpi2cJIB+Xqf10="
   },
   "ps:validFrom": "2011-03-02T00:00:00+0000",
   "ps:validUntil": "2011-03-03T00:00:00+0000"
}
        

2.6 WebPage

The WebPage class is a decorator class for Assets. The decorator is usually found as an additional rdf:type of an Asset which denotes that the asset is a web page of some kind. This is opposed to an opaque byte stream that may or may not be viewable in a web browser.

Status
unstable
Parent Class
owl:Thing
Properties
dc:title, dc:creator, ps:contentUrl, ps:assetProvider, ps:authority, ps:validFrom, ps:validUntil, ps:signature

The following example describes a web page titled "PaySwarm in Practice" that was created by "Digital Bazaar, Inc.". The asset is valid from November 28th 2010 to November 28th 2011.

{
   "@subject": "https://example.org/articles/1#asset",
   "@type": ["ps:Asset", "ps:WebPage"],
   "dc:title": "PaySwarm in Practice",
   "dc:creator": 
   {
      "foaf:name": "Digital Bazaar, Inc.",
   }
   "ps:contentUrl": "https://example.org/articles/1",
   "ps:assetProvider": "https://example.org/person/john-doe#me",
   "ps:authority": "https://payswarm.example.com/about#authority",
   "ps:validFrom": "2010-11-28T00:00:00Z",
   "ps:validUntil": "2011-11-28T00:00:00Z"
   "ps:signature": 
   {
       "@type": "sig:JsonLdSignature",
       "sig:signer": "https://payswarm.example.com/people/john-doe#key-5",
       "sig:signatureValue": "OWM3YzI4OGQzNGVkMzVmMmQ3ODIyZDY3NjI4NTIyZTk2MzQzNmExMgo="
   }
}
        

3. Constants

3.1 NoAdditionalPayees

The NoAdditionalPayees constant is used as a com:rateType value in a com:PayeeRule object to specify that no additional payees are allowed for the associated item. This is typically used when an asset owner does not want anyone else on the network to provide value-added services on top of their asset.

Status
unstable
Domain
com:rateType

The following example specifies that no additional non-PaySwarm Authority payees can be added to the list of payees as a result of the sale of an asset or service.

{
    "@type": "com:PayeeRule",
    "com:rateType": "ps:NoAdditionalPayees",
}
        

4. Properties

4.1 asset

An asset property is used to specify an Asset for sale via PaySwarm. The asset property is typically found in a Listing or a Contract.

Status
unstable
Domain
com:Listing, com:Contract, owl:Thing
Range
com:Asset

The following example shows a portion of a contract containing the description of an Asset that was a part of the purchase.

{
   "@subject": "http://payswarm.example.com/contracts/28394729347",
   "@type": ["ps:Transaction", "ps:Contract"],
   "com:amount": "0.05",
   "com:currency": "USD",
   "com:date": "2011-03-02T03:00:53Z",
   ...
   "ps:asset": 
   {
      "@subject": "http://example.com/articles/1#asset",
      "@type": ["ps:Asset", "ps:WebPage"],
      "dc:creator": 
      {
         "foaf:name": "Bob Smith"
      },
      "dc:title": "PaySwarm in Practice",
      "ps:assetProvider": "https://payswarm.example.com/i/bob",
      "ps:authority": "https://payswarm.example.com/client-config",
      "ps:contentUrl": "http://example.com/articles/1",
      "ps:signature": 
      {
         "@type": "ps:JsonLdSignature",
         "dc:created": "2011-03-02T00:00:00Z",
         "dc:creator": "https://payswarm.example.com/i/bob/keys/4",
         "ps:signatureValue": "XuLEGuq+ne56Qsc5Nic8I="
      }
   },
   "ps:assetAcquirer": "https://payswarm.example.com/i/jane",
   "ps:assetProviderIdentity": 
   {
      "ps:identityHash": "df913752be56fe0d37dcedc2d7f44708373d2a68"
   },
   ...
}
        

4.2 assetAcquirer

An asset acquirer is an entity that is in the process of acquiring or has acquired the rights to a particular asset via a PaySwarm Contract.

Status
unstable
Domain
com:Contract, owl:Thing
Range
xsd:anyURI

The following example shows a contract that specifies a ps:assetAcquirer with a value of https://payswarm.example.com/i/jane.

{
   "@subject": "http://payswarm.example.com/contracts/28394729347",
   "@type": ["ps:Transaction", "ps:Contract"],
   "com:amount": "0.05",
   "com:currency": "USD",
   "com:date": "2011-03-02T03:00:53Z",
   ...
   "ps:assetAcquirer": "https://payswarm.example.com/i/jane",
   "ps:assetProviderIdentity": 
   {
      "ps:identityHash": "df913752be56fe0d37dcedc2d7f44708373d2a68"
   },
   ...
}
        

4.3 assetHash

An asset hash is used as a unique identifier for a graph of asset information. These hashes exist so that the asset provider can refer to the asset by the hash instead of having to re-transmit the entire asset when communicating with a PaySwarm Authority. The hashes also provide a checksum on asset information such that both the asset provider and PaySwarm Authority know that each is talking about the same asset when the hash is used in Web service calls. Asset hash information may be used to make Asset caching decisions by a PaySwarm Authority. The asset hash is generated by following this algorithm:

  1. Encode the Asset sub-graph in JSON-LD normalized form.
  2. Generate a SHA-1 on the JSON-LD normalized form.

When generating an asset hash, the following features must not exist in the Asset graph:

Status
unstable
Domain
ps:Asset
Range
xsd:string

The following example describes a listing that contains information about an ps:Asset as well as the ps:assetHash.

{
    "@subject": "https://example.org/articles/1#listing",
    "@type": "ps:Listing",
    "ps:asset":
    {
        "@subject": "https://example.org/articles/1#asset",
        "@type": ["ps:Asset", "ps:WebPage"],
        "dc:title": "PaySwarm in Practice - Full Article #1",
        "dc:creator": 
        {
           "foaf:name": "Digital Bazaar, Inc.",
        }
        "ps:contentUrl": "https://example.org/articles/1",
        "ps:assetProvider": "https://example.org/person/john-doe#me",
        "ps:authority": "https://payswarm.example.com/about#authority",
        "ps:validFrom": "2010-11-28T00:00:00Z",
        "ps:validUntil": "2011-11-28T00:00:00Z"
        "ps:signature": 
        {
            "@type": "sig:JsonLdSignature",
            "sig:signer": "https://payswarm.example.com/people/john-doe#key-5",
            "sig:signatureValue": "OWM3YzI4OGQzNGVkMzVmMmQ3ODIyZDY3NjI4NTIyZTk2MzQzNmExMgo="
        }
    },
    "ps:assetHash": "37b082b5c45a31d1c4b82da667f74e9b6686a95a"
}
        

4.4 assetProvider

An asset provider is the entity providing an asset for sale. Typically, the assetProvider is the legal owner of the asset that is being listed for sale. Ownership of an asset can manifest in a variety of different forms. Copyright ownership, physical ownership, and sub-leased property or services are just a few of the types of ownership that allow one to be listed as a ps:assetProvider.

Status
unstable
Domain
ps:Listing
Range
xsd:anyURI

The following example describes a ps:Listing that specifies a ps:assetProvider with a value of https://payswarm.example.com/i/bob.

{
   "@subject": "http://example.com/articles/1#listing",
   "@type": ["gr:Offering", "ps:Listing"],
   "com:payee": 
   [
      {
         "@subject": "http://example.com/articles/1#listing-payee",
         "@type": "com:Payee",
         "com:currency": "USD",
         "com:destination": "https://payswarm.example.com/i/bob/accounts/primary",
         "com:rate": "0.05",
         "com:rateType": "com:FlatAmount",
         "rdfs:comment": "Payment for PaySwarm in Practice by Digital Bazaar."
      }
   ],
   "com:payeeRule": 
   [
      {
         "@type": "com:PayeeRule",
         "com:destinationOwnerType": "ps:Authority",
         "com:maximumRate": "10",
         "com:rateType": "com:InclusivePercentage"
      }
   ],
   "ps:asset": "http://example.com/articles/1#asset",
   "ps:assetHash": "14618b56ff597a2fed560db9aa0610fe442106a4",
   "ps:assetProvider": "https://payswarm.example.com/i/bob",
   "ps:license": "http://payswarm.example.com/licenses/blogging",
   "ps:licenseHash": "0d8866836917f8ef58af44accb6efab9a10610ad",
   "ps:signature": 
   {
      "@type": "ps:JsonLdSignature",
      "dc:created": "2011-03-02T00:00:00Z",
      "dc:creator": "https://payswarm.example.com/i/bob/keys/4",
      "ps:signatureValue": "KXtwA5kXZBJzj1rkPMJmGDROjM+fpi2cJIB+Xqf10="
   },
   "ps:validFrom": "2011-03-02T00:00:00+0000",
   "ps:validUntil": "2011-03-03T00:00:00+0000"
}
        

4.5 authority

An authority is used to specify a PaySwarm authority that should be used to process contracts containing a particular Listing or Asset.

Status
unstable
Domain
ps:Listing, ps:Asset, owl:Thing
Range
xsd:anyURI

The following example describes an asset that specifies that any purchase of the asset should be performed via the https://payswarm.example.com/client-config PaySwarm Authority.

{
   "@subject": "http://example.com/videos#cell-division",
   "@type": ["ps:Asset", "ps:Data"],
   "dc:creator": 
   {
      "foaf:name": "John Doe"
   },
   "dc:title": "Learning How Cells Divide",
   "ps:assetProvider": "https://payswarm.example.com/i/john",
   "ps:authority": "https://payswarm.example.com/client-config",
   "ps:contentUrl": "http://example.com/video/cell-division.mpg",
   "ps:signature": 
   {
      "@type": "ps:JsonLdSignature",
      "dc:created": "2011-03-12T00:00:00Z",
      "dc:creator": "https://payswarm.example.com/i/john/keys/2",
      "ps:signatureValue": "ne56Qsc5IXuLEGuq+Nic8="
   }
}
        

4.6 contentUrl

The content URL is used to specify the viewing or the download location for a particular piece of content. The content URL is usually specified along-side the asset in the event that the asset description is expressed in a place that is different from the location of the asset.

Status
unstable
Domain
com:Asset, owl:Thing
Range
xsd:anyURI

The following example demonstrates an asset that has a content URL specified as https://example.org/articles/1.

{
   "@subject": "https://example.org/articles/1#asset",
   "@type": ["ps:Asset", "ps:WebPage"],
   "dc:title": "PaySwarm in Practice",
   "dc:creator": 
   {
      "foaf:name": "Digital Bazaar, Inc.",
   }
   "ps:contentUrl": "https://example.org/articles/1",
   "ps:assetProvider": "https://example.org/person/john-doe#me",
   "ps:authority": "https://payswarm.example.com/about#authority",
   "ps:validFrom": "2010-11-28T00:00:00Z",
   "ps:validUntil": "2011-11-28T00:00:00Z"
   "ps:signature": 
   {
       "@type": "sig:JsonLdSignature",
       "sig:signer": "https://payswarm.example.com/people/john-doe#key-5",
       "sig:signatureValue": "OWM3YzI4OGQzNGVkMzVmMmQ3ODIyZDY3NjI4NTIyZTk2MzQzNmExMgo="
   }
}
        

4.7 licenseTemplate

The license template is used to express the boilerplate language in a license. The template is usually expressed in HTML and contains portions of markup that are replaceable via software. For example, a section of the ps:licenseTemplate may contain the following markup: . The previous code snippet would be expanded when the license is displayed. For instance, the number of times a document may be physically reproduced could be placed into the span element, like so: 5. The ps:licenseTemplate is frequently used in combination with the ps:licenseTerms property.

Status
unstable
Domain
ps:License, owl:Thing
Range
xsd:string

The following example shows how a license template is used in conjunction with a set of license terms.

{
   "@subject": "http://payswarm.example.com/licenses/personal-use",
   "@type": "ps:License",
   "dc:format": "text/html",
   "ps:licenseTemplate": "This personal use license allows you to save the 
      purchased item onto any device that you own for your personal enjoyment
      and make up to <span property=\"ex:physicalCopies\" /> printed
      copies of the work for personal use.",
   "ps:licenseTerms": 
   {
      "ex:physicalCopies": 5
   }
}
        

4.8 licenseTerms

The license terms are used in conjunction with the ps:licenseTemplate to create the final license that is associated with a PaySwarm contract. The license term values are used to insert specific values into the license template.

Status
unstable
Domain
ps:License
Range
xsd:string

The example below specifies a license with a single term that limits the number of printed physical copies of a work to 5.

{
   "@subject": "http://payswarm.example.com/licenses/personal-use",
   "@type": "ps:License",
   "dc:format": "text/html",
   "ps:licenseTemplate": "This personal use license allows you to save the 
      purchased item onto any device that you own for your personal enjoyment
      and make up to <span property=\"ex:physicalCopies\" /> printed
      copies of the work for personal use."
   "ps:licenseTerms": 
   {
      "ex:physicalCopies": 5
   }
}
        

4.9 identityHash

The identity hash is used to provide a means of identifying an individual that is a participant in a sale, but in a way that does not violate their privacy. At times, an asset acquirer may need to prove to a court of law that an asset provider has broken the terms of a license in a contract. For instance, this may need to happen if the asset aquirer is seeking damages from the asset provider. PaySwarm protects identities by encrypting data such as address information and names in contracts. This ensures that even if a contract is posted to the Internet, it will be nearly impossible to discover the names and addresses of the participants in the contract if the participants do not want that information to be known. Instead of including real names and addresses in the PaySwarm contracts, an identityHash is calculated and included in the contract.

The identity hash is generated by performing the following hashing algorithm:

  1. Collect the formatted name for the person as well as the primary address for the individual.
  2. Convert the information to lower-case if it is supported in the character set for the language.
  3. Generate a random 6-byte identity salt.
  4. Concatenate the formatted name, address and identity salt together.
  5. Perform a SHA-1 hash of the information, the result is the identityHash value.

The identity hash is only used for asset providers and only those providers that are providing an asset other than data. If an asset provider is providing raw data, then it is assumed that they have implicitly given access to that data. There are no rights involved other than the data access itself and the contract is considered fairly temporal.

If the asset provider is not providing data then they are providing rights to an asset where the creator of that asset is known. However, the home address of that person is not necessarily known. If the home address of the asset provider is a matter of public record then the identityHash scheme cannot reliably protect that knowledge. This means that a person's address can be determined just from their name anyway, even without using PaySwarm.

However, if an asset provider's address is not a matter of public record, the identityHash scheme protects that entity's address because the set of all addresses where an entity has resided are not available and are thus much harder to crack using a brute force attack. It is true though, that all addresses where that entity might have lived within an entire state or country might be available. If that is the case, it is typically not feasible to try every possible address in the region because the number of permutations are too high.

That is, if the entity's information has ever been made public, then it's likely easier to check public records than it is to crack the identityHash for a PaySwarm contract. Since CPU power will continue to improve over time, an implementation must ensure that it is sufficiently difficult to test the sufficiently small set of addresses that an attacker believes an entity has resided.

In order ensure that a brute force attack remains infeasible, a random number is appended to the identity data that is hashed. This approach is nearly identical to the concept of a salt, except that this salt does not just protect against dictionary attacks, it protects against computational attacks because the salt is kept secret. In practice, the salt is thrown away after use. The salt can be discarded because, in the event of a court order to perform discovery on the participants involved in a contract, there will be a very small data set to search. The small data set is relative to the "guess set" a brute force attacker would have to use to look for a hash match.

A court of law attempting to discover the identity of a contract participant can test all random numbers (possible salts) along with each address in the set for the entity that is a part of the case. The random number should be sufficiently small that a program can test identities when subpoenaed but sufficiently large to thwart brute-force attacks. The random number can increase in range with time as CPU power increases. Note that this test only needs to be run if the PaySwarm authority involved has ceased to exist or records of the purchase no longer exist.

Status
unstable
Domain
ps:Contract, owl:Thing
Range
xsd:string

The following snippet of a contract contains the asset provider's identity which is hashed to protect the physical location at which the asset provider resides.

{
   "@subject": "http://payswarm.example.com/contracts/28394729347",
   "@type": ["ps:Transaction", "ps:Contract"],
   "ps:asset": { ... },
   "ps:assetProviderIdentity": 
   {
      "ps:identityHash": "df913752be56fe0d37dcedc2d7f44708373d2a68"
   },
   ...
}
        

4.10 license

The license specifies a URL where the rights to an asset are described. Licenses are typically included in a Listing to express the rights that are conferred upon purchase. Licenses are also included in contracts to express the rights that govern the access and use of the asset. The value of this property is typically a URL which expresses a ps:licenseTemplate using HTML+RDFa or other human-readable semantic web markup language.

Status
unstable
Domain
ps:Listing, ps:Contract, owl:Thing
Range
xsd:anyURI

The following contract snippet below demonstrates how a license is expressed in a completed contract.

{
   "@subject": "http://payswarm.example.com/contracts/982378927357",
   "@type": ["ps:Transaction", "ps:Contract"],
   "ps:asset": { ... },
   "ps:license":
   {
      "@subject": "http://payswarm.example.com/licenses/personal-use",
      "@type": "ps:License",
      "dc:format": "text/html",
      "ps:licenseTemplate": "This personal use license allows you to save the 
         purchased item onto any device that you own for your personal enjoyment
         and make up to <span property=\"ex:physicalCopies\" /> printed
         copies of the work for personal use."
      "ps:licenseTerms": 
      {
         "ex:physicalCopies": 5
      }
   }
   ...
}
        

4.11 licenseHash

The licenseHash is a cryptographic hashing of the contents of a license. Specifically, it is a hashing of the ps:licenseTemplate using the SHA-1 hashing algorithm.

Status
unstable
Domain
ps:Listing, ps:Contract
Range
xsd:string

The following listing snippet example below shows a license URL coupled with a licenseHash. A software agent working with the information may depend on a cache to determine whether or not the information associated with the ps:license would need to be fetched from the Web based on the value of the license hash.

{
   "@subject": "http://example.com/articles/1#listing",
   "@type": ["gr:Offering", "ps:Listing"],
   "ps:license": "http://payswarm.example.com/licenses/blogging",
   "ps:licenseHash": "0d8866836917f8ef58af44accb6efab9a10610ad"
   ...
}
        

4.12 listing

A listing encapsulates an offer for sale. It typically includes an Asset and a License that governs the post-purchase use of that asset.

Status
unstable
Domain
ps:Contract, owl:Thing
Range
ps:Listing

The following contract snippet shows the portion of the contract that contains the listing information.

{
   "@subject": "http://payswarm.example.com/contracts/28394729347",
   "@type": ["ps:Transaction", "ps:Contract"],
   "com:amount": "0.05",
   "com:currency": "USD",
   "com:date": "2011-03-02T03:00:53Z",
   ...
   "ps:listing": 
   {
      "@subject": "http://example.com/articles/1#listing",
      "@type": ["gr:Offering", "ps:Listing"],
      "com:payee": 
      [
         {
            "@subject": "http://example.com/articles/1#listing-payee",
            "@type": "com:Payee",
            "com:currency": "USD",
            "com:destination": "https://payswarm.example.com/i/bob/accounts/primary",
            "com:rate": "0.05",
            "com:rateType": "com:FlatAmount",
            "rdfs:comment": "Payment for PaySwarm in Practice by Digital Bazaar."
         }
      ],
      "com:payeeRule": 
      [
         {
            "@type": "com:PayeeRule",
            "com:destinationOwnerType": "ps:Authority",
            "com:maximumRate": "10",
            "com:rateType": "com:InclusivePercentage"
         }
      ],
      "ps:asset": "http://example.com/articles/1#asset",
      "ps:assetHash": "14618b56ff597a2fed560db9aa0610fe442106a4",
      "ps:license": "http://payswarm.example.com/licenses/blogging",
      "ps:licenseHash": "0d8866836917f8ef58af44accb6efab9a10610ad",
      "ps:signature": 
      {
         "@type": "ps:JsonLdSignature",
         "dc:created": "2011-03-02T00:00:00Z",
         "dc:creator": "https://payswarm.example.com/i/bob/keys/4",
         "ps:signatureValue": "KXtwA5kXZBJzj1rkPMJmGDROjM+fpi2cJIB+Xqf10="
      },
      "ps:validFrom": "2011-03-02T00:00:00+0000",
      "ps:validUntil": "2011-03-03T00:00:00+0000"
   },
   "ps:listingHash": "1acbd23c3a7d8827270a959a2760f7c4ded98022",
   ...
}
        

4.13 listingHash

A listing hash is a checksum for the contents of a listing. Technically, it is a cryptographic hash of the graph information expressed in JSON-LD. To calculate a listing hash, the entire ps:listing sub-tree without any ps:signature values is normalized via standard JSON-LD normalization rules and then the SHA-1 hashing algorithm is performed on the result.

Status
unstable
Domain
ps:Contract, owl:Thing
Range
xsd:string

The contract snippet below shows the listing hash that is associated with the listing. A software agent working with the information may depend on a cache to determine whether or not the information associated with the ps:listing would need to be fetched from the Web based on the value of the listing hash.

{
   "@subject": "http://payswarm.example.com/contracts/583272397238",
   "@type": ["ps:Transaction", "ps:Contract"],
   ...
   "ps:listing": "http://example.com/articles/1#listing",
   "ps:listingHash": "1acbd23c3a7d8827270a959a2760f7c4ded98022",
   ...
}
        

4.14 owner

An owner is typically an entity that fully or partially has rights or control over a particular resource. This property is most often used to express that a particular entity owns a public key, but may be used for other resources such as claiming ownership over a financial com:Account resource.

Status
unstable
Domain
com:Account, owl:Thing
Range
xsd:anyURI

The following example demonstrates the expression of a public key belonging to the identity https://payswarm.example.com/i/bob.

{
   "@subject": "https://payswarm.example.com/i/bob/keys/1",
   "@type": "sig:Key",
   "ps:owner": "https://payswarm.example.com/i/bob",
   "sig:publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMIIBG0BA...OClDQAB\n-----END PUBLIC KEY-----\n"
}
        

4.15 validFrom

The valid from property specifies the point at which a piece of information becomes reliable. It is often used to specify when Assets or Listings start their validity period. The information can be used to determine caching metrics.

Status
unstable
Domain
ps:Listing, owl:Thing
Range
xsd:dateTime

The following example is of an Asset that has a validity period starting at midnight on November 28th, 2010.

{
   "@subject": "https://example.org/articles/1#asset",
   "@type": ["ps:Asset", "ps:WebPage"],
   "dc:title": "PaySwarm in Practice",
   "dc:creator": 
   {
      "foaf:name": "Digital Bazaar, Inc.",
   }
   "ps:contentUrl": "https://example.org/articles/1",
   "ps:assetProvider": "https://example.org/person/john-doe#me",
   "ps:authority": "https://payswarm.example.com/about#authority",
   "ps:validFrom": "2010-11-28T00:00:00Z",
   "ps:validUntil": "2011-11-28T00:00:00Z"
   "ps:signature": 
   {
       "@type": "sig:JsonLdSignature",
       "sig:signer": "https://payswarm.example.com/people/john-doe#key-5",
       "sig:signatureValue": "OWM3YzI4OGQzNGVkMzVmMmQ3ODIyZDY3NjI4NTIyZTk2MzQzNmExMgo="
   }
}
        

4.16 validUntil

The valid until property specifies the point at which a piece of information ceases to be reliable. It is often used to specify when Assets or Listings expire. The information can be used to determine caching metrics.

Status
unstable
Domain
ps:Listing, owl:Thing
Range
xsd:dateTime

The following example is of an Asset that has a validity period ending at midnight on November 28th, 2011.

{
   "@subject": "https://example.org/articles/1#asset",
   "@type": ["ps:Asset", "ps:WebPage"],
   "dc:title": "PaySwarm in Practice",
   "dc:creator": 
   {
      "foaf:name": "Digital Bazaar, Inc.",
   }
   "ps:contentUrl": "https://example.org/articles/1",
   "ps:assetProvider": "https://example.org/person/john-doe#me",
   "ps:authority": "https://payswarm.example.com/about#authority",
   "ps:validFrom": "2010-11-28T00:00:00Z",
   "ps:validUntil": "2011-11-28T00:00:00Z"
   "ps:signature": 
   {
       "@type": "sig:JsonLdSignature",
       "sig:signer": "https://payswarm.example.com/people/john-doe#key-5",
       "sig:signatureValue": "OWM3YzI4OGQzNGVkMzVmMmQ3ODIyZDY3NjI4NTIyZTk2MzQzNmExMgo="
   }
}
        

A. References

A.1 Normative references

No normative references.

A.2 Informative references

No informative references.