Proposed Versioning and Status Behaviour for Credential Schemas

[KDwevedi]

Description

This post is a followup to this discussion on credential APIs and references these schema api specifications as context.

CC - @tejash-jl @rahul101001000 @suresh12

There is a need to define versioning and status behaviour for credential schemas in order to define valid functioning behaviour for APIs.

Proposed Versioning and Status Behaviour for Credential Schemas

This proposal will attempt to define the versioning behaviour for credential schemas in case of two possible events:

• Addition of a new schema
• Updation of an existing schema

In addition, it will attempt to define how versioning affects what responses one should expect on GET requests along with the impact on dependent templates and credentials as dependent on schema status and versioning.

Identifying a Schema: A schema is uniquely identified by the combination of its DID and Version.

---

Status and Versioning

A description of Schema Statuses and corresponding Versioning Behaviour:

Current Status	Description	GET Request by SchemaID	Can Change To	Versioning Behaviour
DRAFT	A newly created schema is a DRAFT until published.	Returns only the specified draft schema.	PUBLISHED via PUT request	Updated via PUT requests. Version number as specified by Issuer. No change in version number occurs on updates.
PUBLISHED	A PUBLISHED schema is the latest version of that schema.	Returns only the specified published schema	DEPRECATED via PUT request REVOKED via PUT request	Updated via PUT request. Updates in core attributes change major version number, older version is DEPRECATED and both versions persist. Updates in metadata (tags) changes minor version number, only newer version persists.
DEPRECATED	A DEPRECATED schema is an older version of that schema.	Returns the schema, a 'Deprecated' warning, the current PUBLISHED version number.	N/A	Cannot be updated (in order to avoid branching versions).
REVOKED	A REVOKED schema is invalid.	Returns the schema with 'Revoked' warning.	PUBLISHED via PUT Request	Updated via PUT request as latest PUBLISHED version with major version number change.

Impact on Templates and Credentials:

Status	Template Issuance	Template Validation	Credential Issuance	Credential Validation	Credential Revocation
DRAFT	Cannot be issued. HTTP Status 403.	Cannot be validated. HTTP Status 403.	Cannot be issued. HTTP Status 403.	Cannot be validated HTTP Status 403.	N/A
PUBLISHED	Can be issued. HTTP Status 201.	Can be validated. HTTP Status 200.	Can be issued. HTTP Status 201.	Can be validated. HTTP Status 200.	Can be revoked. HTTP Status 200.
DEPRECATED	Can be issued. Generates 'Deprecated' warning. HTTP Status 201.	Can be validated. Generates 'Deprecated' warning. HTTP Status 200.	Can be issued. HTTP Status 201.	Can be validated HTTP Status 200.	Can be revoked HTTP Status 200.
REVOKED	Cannot be issued.	Cannot be validated.	Cannot be issued.	?	?

Relevant HTTP Status Codes and Usecases:

• Successful Responses:
  • 200 OK
    • For valid requests that succeed but create no new resource.
    • Example: Successful GET requests for schemas.
  • 201 Created
    • For valid requests that create new resources.
    • Example: Issuing a new credential schema.
• Client Error Responses:
  • 400 Bad Request
    • Used in case of malformed or invalid requests.
  • 401 Unauthorized
    • Incase the request contains incomplete or invalid authentication information.
    • Example: Attempt to update a schema issued by someone else.
  • 403 Forbidden
    • Requests to resources that should not be exposed to those types of requests.
    • Example: Attempt to issue a credential against a draft schema.
  • 404 Not Found
    • For resources not found in the database.

Experience for End User:

Holder of the Credential:
Since credentials can only be issued by published and deprecated schemas and both statuses allow for continued issuance and validaion, the holder of the credential remains unaffected by either status. The effect of revoking a credential schema on complying credentials is undefined and needs to be clarified (see questions).
.

Issuer of Credenial:
GET requests via tags always return the latest version of schemas so that newly compliant issuers onboard on the latest version.
Deprecated versions can only be accessed by a combination of their did and specific version number. This means that systems using deprecated schemas can still access them, insuring backward compatibility. The warnings to upgrade to newer versions should create a soft push to align the system to the latest standards.
Draft and Revoked schemas while issuing credentials are not relevant to issuers since credentials cannot be issued against them. The effect of revoking a credential schema on complying credentials is undefined and needs to be clarified (see
questions).

Issuer of Schemas:
Allowing credentials to be validated against deprecated schemas allows the freedom to make changes to schemas without disruption.
The draft functionality allows a lowstakes environment to finalise schemas while they are finalised for publishing (see suggestions).

Questions:

My current understanding of the REVOKED status is that it declares the schema to be invalid, presumably invalidating complying credentials as well. If that understanding is correct,

• What would be the anticipated use cases where this functionality would be used?
• What would be the resulting effect on all the credentials complying to this schema?

Suggestions:

• An attribute in the record for a schema should point to the immediate predecessor and successor version of that schema in order that the schema update histories can be accessed.
• Currently the DRAFT status is being utillised as a transition state only upon the creation of a new schema that is, a schema is only a draft if it is being created but has not yet been published. We should instead leverage DRAFT as a transitory state for all updation requests as well. This will allow space for review and minimize versioning updates for corrections such as typos.

---