Schema versioning vs. API versioning

GRCSChema.org does track schema versions (see version). However, each ISV should be using the best practice of tying their API version to related API keys.

Using API keys to control API versioning instead of different versioned URLs can be an effective strategy, offering both flexibility and control over API access and usage. This method allows API producers to assign different API versions to specific keys, enabling them to manage who can access which version of an API without changing the URL structure. This approach can also facilitate smoother transitions between API versions for consumers, as it avoids the need to reconfigure URLs or deal with potential conflicts between different versions.

API keys are typically included in the API request as a header, query string, or sometimes as a cookie, and are used to authenticate and authorize access to an API. By tying specific versions to different API keys, producers can easily control access to various versions of an API. This setup helps in managing API versions effectively by routing requests to appropriate versions based on the API key provided, ensuring that clients are accessing the correct version of the API without impacting other users who may still be on an older version¹.

For instance, in Azure API Management, different versions of an API can be managed and presented as distinct entities. These versions are often accessed through different API keys, each potentially corresponding to different versions as specified by the API management strategy. This allows clients to choose which version of the API they want to interact with, providing flexibility and control over API deployment and usage².

This method of versioning also simplifies the management of breaking changes and new features, allowing API producers to roll out changes gradually while still supporting older API versions. Additionally, it enhances security by allowing finer control over who can access specific features of an API, depending on the version³.

One possible approach

In JSON-LD, the version of an API or data format that a "Thing" complies with can be specified directly within the JSON-LD document itself. This is achieved by using a version property or a similar mechanism to indicate which version of the schema or API the JSON-LD data is intended to work with. Here's how you could approach integrating an API version within a JSON-LD structure:

1. Using a Custom Property: You can introduce a custom property, such as apiVersion, within your JSON-LD to denote the version of the API. This property would be specific to your application and understood by your API to determine how to process the JSON-LD data correctly.
2. Standard "@context" Usage: While the @context property in JSON-LD is primarily used to define the vocabulary for terms used in a document, it could also include versioning information if the context URL itself is versioned. For example, you might have a context URL like "@context": "https://example.com/contexts/thing-v1" where v1 indicates the version.
3. Schema Versioning: Because you are using GRCSchema.org there are version-specific contexts available, you can point to the specific version of the schema that matches the API version. This ensures that the definitions and semantics of the data properties used align with the specific API version.

Here’s an example snippet of what such a JSON-LD might look like:

{
  "@context": "https://example.com/contexts/thing-v1",
  "@type": "Thing",
  "apiVersion": "1.0",
  "name": "Example Thing",
  "description": "This is an example of a Thing using a specific API version."
}

In this example:

• The @context provides the URI that is versioned, which helps in understanding the terms according to the version.
• The apiVersion is a custom property that explicitly states the version of the API that the JSON-LD data format is intended to comply with.

Using such methods allows client applications to handle the data correctly based on the version of the API or schema expected by the server, thereby maintaining compatibility across different versions of the API or data schema.