Indy HIPE 0149: Rich Schema Schemas¶

Authors: Brent Zundel brent.zundel@evernym.com, Ken Ebert ken@sovrin.org, Alexander Shcherbakov alexander.shcherbakov@evernym.com
Start Date: 2019-11-01

Status¶

Status: PROPOSED
Status Date: 2019-11-01
Status Note: part of Rich Schema work

Summary¶

The proposed schemas are JSON-LD objects. This allows credentials issued according to the proposed schemas to have a clear semantic meaning, so that the verifier can know what the issuer intended. They support explicitly typed properties and semantic inheritance. A schema may include other schemas as property types, or extend another schema with additional properties. For example a schema for “employee” may inherit from the schema for “person.”

Schema objects are processed in a generic way defined in Rich Schema Objects Common.

Motivation¶

Many organizations, such as HL7 who publish the FHIR standard for heath care data exchange, have invested time and effort into creating data schemas that are already in use. Many schemas are shared publicly via web sites such as https://schema.org/, whose mission is, “to create, maintain, and promote schemas for structured data on the Internet, on web pages, in email messages, and beyond.”

These schemas ought to be usable as the basis for verifiable credentials.

Although verifiable credentials are the primary use case for schemas considered in this document, other future uses may include defining message formats or objects in a verifiable data registry.

Interoperability¶

Existing applications make use of schemas to organize and semantically describe data. Using those same schemas within anonymous credentials provides a means of connecting existing applications with this emerging technology. This allows for an easy migration path for those applications to incorporate anonymous credentials.

Using schemas which may be shared among verifiable credential ecosystems allows for semantic interoperability between them, and enables a path toward true multi-lateral credential exchange.

Using existing schemas, created in accordance with widely-supported common standards, allows anonymous credentials to benefit from the decades of effort and thought that went into those standards and to work with other applications which also adhere to those standards.

Re-use¶

Rich schemas can be re-used within Indy. Because these schemas are hierarchical and composable, even unrelated schemas may share partial semantic meaning due to the commonality of sub-schemas within both. For example, a driver license schema and an employee record are not related schemas, but both may include a person schema.

A schema that was created for a particular use-case and accepted within a trust framework may be re-used within other trust frameworks for their use-cases. The visibility of these schemas across trust boundaries increases the ability of these schemas to be examined in greater detail and evaluated for fitness of purpose. Over time the schemas will gain reputation.

Extensibility¶

Applications can use these schemas as a basis for complex data objects for use within the application, or exposed through external APIs.

Immutability¶

One important aspect of relying on schemas to provide the semantic meaning of data within a verifiable credential, is that the meaning of the credential properties should not change. It is not enough for entities within the ecosystem to have a shared understanding of the data in the present, it may be necessary for them to have an understanding of the credential at the time it was issued and signed. This depends on the trust framework within which the credential was issued and the needs of the parties involved. The Indy ledger can provide immutable storage of schemas.

Tutorial¶

Intro to Schemas¶

schema objects are used to enforce structure and semantic meaning on a set of data. They allow Issuers to assert, and Holders and Verifiers to understand, a particular semantic meaning for the properties in a credential.

Rich schemas are JSON-LD objects. Examples of the type of schemas supported here may be found at schema.org. At this time we do not support other schema representations such as RDFS, JSON Schema, XML Schema, OWL, etc.

Properties¶

Rich Schema’s properties follow the generic template defined in Rich Schema Common.

Rich Schema’s content field is a JSON-LD-serialized string with the following fields:

@id¶

A rich schema must have an @id property. The value of this property must be equal to the id field which is a DID (see Identification of Rich Schema Objects).

A rich schema may refer to the @id of another rich schema to define a parent schema. A property of a rich schema may use the @id of another rich schema as the value of its @type or @id property.

A mapping object will contain the @id of the rich schema being mapped.

A presentation definition will contain the @id of any schemas a holder may use to present proofs to a verifier.

@type¶

A rich schema must have a @type property. The value of this property must be (or map to, via a context object) a URI.

@context¶

A rich schema may have a @context property. If present, the value of this property must be a context object or a URI which can be dereferenced to obtain a context object.

Use in Verifiable Credentials¶

These schemas will be used in conjunction with the JSON-LD representation of the verifiable credentials data model to specify which properties may be included as part of the verifiable credential’s credentialSubject property, as well as the types of the property values.

The @id of a rich schema may be used as an additional value of the type property property of a verifiable credential. Because the type values of a verifiable credential are not required to be dereferenced, in order for the rich schema to support assertion of the structure and semantic meaning of the claims in the credential, an additional reference to the rich schema should be made through the credentialSchema property. This may be done as a direct reference to the rich schema @id, or via another rich schema object which references the rich schema @id such as a credential definition as would be the case for anonymous credentials, as discussed in the mapping section of the rich schema overview RFC.

Example Schema¶

An example of the content field of a Rich Schema object:

   "@id": "did:sov:2f9F8ZmxuvDqRiqqY29x6dx9oU4qwFTkPbDpWtwGbdUsrCD",
   "@type": "rdfs:Class",
   "@context": {
    "schema": "http://schema.org/",
    "bibo": "http://purl.org/ontology/bibo/",
    "dc": "http://purl.org/dc/elements/1.1/",
    "dcat": "http://www.w3.org/ns/dcat#",
    "dct": "http://purl.org/dc/terms/",
    "dcterms": "http://purl.org/dc/terms/",
    "dctype": "http://purl.org/dc/dcmitype/",
    "eli": "http://data.europa.eu/eli/ontology#",
    "foaf": "http://xmlns.com/foaf/0.1/",
    "owl": "http://www.w3.org/2002/07/owl#",
    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
    "rdfa": "http://www.w3.org/ns/rdfa#",
    "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
    "schema": "http://schema.org/",
    "skos": "http://www.w3.org/2004/02/skos/core#",
    "snomed": "http://purl.bioontology.org/ontology/SNOMEDCT/",
    "void": "http://rdfs.org/ns/void#",
    "xsd": "http://www.w3.org/2001/XMLSchema#",
    "xsd1": "hhttp://www.w3.org/2001/XMLSchema#"
  },
  "@graph": [
    {
      "@id": "schema:recipeIngredient",
      "@type": "rdf:Property",
      "rdfs:comment": "A single ingredient used in the recipe, e.g. sugar, flour or garlic.",
      "rdfs:label": "recipeIngredient",
      "rdfs:subPropertyOf": {
        "@id": "schema:supply"
      },
      "schema:domainIncludes": {
        "@id": "schema:Recipe"
      },
      "schema:rangeIncludes": {
        "@id": "schema:Text"
      }
    },
    {
      "@id": "schema:ingredients",
      "schema:supersededBy": {
        "@id": "schema:recipeIngredient"
      }
    }
  ]

recipeIngredient schema from schema.org.

Stored on Ledger¶

Rich Schema will be written to the ledger in a generic way defined in Rich Schema Objects Common.

Indy Node Rich Schema API¶

Indy Node processes ledger transaction requests via request handlers.

There is a write request handler for RICH_SCHEMA transaction. The numerical code for a RICH_SCHEMA transaction is 201.

A Rich Schema can be obtained from the Ledger by the generic GET_RICH_SCHEMA_OBJECT_BY_ID and GET_RICH_SCHEMA_OBJECT_BY_METADATA requests (see Rich Schema Objects Common). The numerical code for a GET_RICH_SCHEMA_OBJECT_BY_ID transaction is 300. The numerical code for a GET_RICH_SCHEMA_OBJECT_BY_METADATA transaction is 301.

RICH_SCHEMA Transaction¶

Adds a Rich Schema object as part of Rich Schema feature.

It’s not possible to update an existing Rich Schema. If the Rich Schema needs to be evolved, a new Rich Schema with a new id and name-version needs to be created.

id (string):

A unique ID (for example a DID with an id-string being base58 representation of the SHA2-256 hash of the content field)
content (json-serialized string):

Rich Schema object as JSON serialized in canonical form. This value must be a json-ld, rich schema object. json-ld supports many parameters that are optional for a rich schema txn. However, the following parameters must be there:
- @id: The value of this property must be (or map to, via a context object) a URI.
- @type: The value of this property must be (or map to, via a context object) a URI.
- @context(optional): If present, the value of this property must be a context object or a URI which can be dereferenced to obtain a context object.
rsType (string enum):

Rich Schema’s type. Currently expected to be sch.
rsName (string):

Rich Schema’s name
rsVersion (string):

Rich Schema’s version

The combination of rsType, rsName, and rsVersion must be unique among all rich schema objects on the ledger.

The generic patterns for RICH_SCHEMA transaction, request, and reply can be found in Rich Schema Objects Common.

Indy VDR API¶

Indy VDR methods for adding and retrieving a Rich Schema from the ledger comply with the generic approach described in Rich Schema Objects Common.

This means the following methods can be used:

indy_vdr_build_rich_schema_object_request
indy_vdr_build_get_schema_object_by_id_request
indy_vdr_build_get_schema_object_by_metadata_request

Note About Existing Indy Schemas¶

This HIPE and associated RFC does not add support here or through Aries for existing Indy schemas (which only contain a simple array of attribute names).

Reference¶

More information on the Verifiable Credential data model use of schemas may be found here

Drawbacks¶

Rich schema objects introduce more complexity.

Unresolved Questions and Future Work¶

We are not defining Rich Schema objects as DID DOCs for now. We may re-consider this in future once DID DOC format is finalized.
It may make sense to extend DID specification to include using DID for referencing Rich Schema objects.
The proposed canonicalization form of a content to be used for DID’s id-string generation is in a Draft version, so we may find a better way to do it.
We don’t check if the specified @context is valid by resolving all external links.
We may introduce more discovery features in future.
Future work may include methods for anchoring to Indy a Rich Schema which is immutably stored elsewhere.