Pre-release. Until the official launch, content may change, including published files.
Skip to content

Source: https://datamodels.jp/en/guide/urls · Text CC BY 4.0

URLs and versions ​

A @context URL is stored with every entity and read years later. This page says which URL to use, what the catalog promises about it, and how models change without breaking it.

Pre-release

These promises apply from the official launch. Until then, published files, v1.0.0 included, may still be corrected in place, and exact versions are cached for 5 minutes instead of a year. Do not reference them from production data before the launch.

Which URL to use ​

PurposeURL
@context of stored data, Link headerversion alias /context/<subject>/v1.jsonld
Audits, reproducing a result on another brokerexact version /context/<subject>/v1.0.0.jsonld
Validation/schema/<subject>/<Type>/v1.json (version alias) or v1.0.0.json

The version alias moves only to compatible versions, so it is the right default. Use the exact version when you need to audit or reproduce a result.

Servers and brokers may keep a copy: the version alias for 5 minutes, so a new compatible version reaches everyone within 5 minutes; an exact version for a year, because it never changes (from the official launch; until then also 5 minutes).

v1.0.0v1.1.0v1.2.0v2.0.0published versions: never changev1.jsonldversion alias: latest 1.xv2.jsonldincompatible change

The promises ​

  1. A published versioned file is never changed or removed. /context/<subject>/v1.0.0.jsonld stays the same forever. On every pull request, CI compares the published files with the main branch and with the live site, and rejects a change to one.
  2. The meaning of an attribute never changes. When it must, the catalog adds a new attribute and marks the old one deprecated.
  3. Type and attribute IRIs lead to documentation. Opening https://datamodels.jp/ns/transportation/RoadRestriction in a browser shows the type's page. A program that asks for JSON-LD (Accept: application/ld+json) is sent to the subject's vocabulary instead (/vocab/transportation/v1.jsonld), which defines the type with its labels and description.

Versions ​

Each subject has one version number, shared by its @context, vocabulary and JSON Schemas (for example transportation 1.0.0). Numbers follow Semantic Versioning:

ChangeNumberExample
A fix that changes neither meaning nor validationpatch (1.0.1)a typo in a schema description
A compatible additionminor (1.1.0)a new optional attribute or model, a new allowed value
An incompatible changemajor (2.0.0)renaming an attribute or changing its type, removing an attribute or a value, making an optional attribute required

A new version does not replace the old one: v1.0.0 stays at its URL, and the version alias v1 points to the latest 1.x. A new allowed value is a minor version, but code that handles every value needs to learn it, so the pull request and the model's notes say so.

Deprecation ​

  • An attribute that is being replaced is marked deprecated in the schema and on the model page. It stays at least until the next minor version and is removed only in a major version.
  • A model that should not be used for new work is marked deprecated. It stays published at the same URLs. If there is a replacement, its page and catalog.json name it (supersededBy).

Verifying a file ​

digests in catalog.json lists a SHA-256 digest for every versioned file: the @context, vocabulary and JSON Schemas of every published version (for example /schema/common/Geometry/v1.0.0.json). The form is the one Subresource Integrity uses, sha256-<base64>.

  • Pin it: write the digest of each file you use into your own configuration or lock file, and compare it whenever you load the file. A change no longer goes unnoticed. During the pre-release, before the official launch, a published file may still be corrected, and its digest changes with it.
  • Compare with the repository: every published version is also in the GitHub repository, under models/<subject>/releases/v<version>/. A digest computed from there is checked over a different path than the one datamodels.jp serves. The files in the repository match the URLs as follows:
    • context.jsonld: /context/<subject>/v<version>.jsonld
    • vocab.jsonld: /vocab/<subject>/v<version>.jsonld
    • schema/<Type>.json: /schema/<subject>/<Type>/v<version>.json

To compute a digest, run the command below (it saves the file to a temporary file first, so a failed download prints nothing, and removes it at the end) and put sha256- in front of its output; the result has the same form as the values in digests.

bash
f=$(mktemp)
curl -fsSo "$f" https://datamodels.jp/schema/common/Geometry/v1.0.0.json \
  && openssl dgst -sha256 -binary "$f" | openssl base64 -A
rm -f "$f"

The digests come from the same site as the files. They show that a copy or a cache matches what was published, but not that the site itself was not changed; for that, compare with the files in the repository. There are no signatures.

All URLs ​

URLWhat it is
/context/<subject>/vX.Y.Z.jsonld@context (immutable)
/context/<subject>/vX.jsonldversion alias (latest X.y.z)
/schema/<subject>/<Type>/vX.Y.Z.jsonJSON Schema (immutable)
/schema/<subject>/<Type>/vX.jsonversion alias
/vocab/<subject>/vX.Y.Z.jsonldvocabulary (RDFS: classes, subclass relations, ja/en labels; immutable)
/vocab/<subject>/vX.jsonldversion alias
/examples/<subject>/<Type>/example.jsonexample (key-values form)
/examples/<subject>/<Type>/example-normalized.jsonldexample (normalized form; not for value types)
/ns/<subject>/<Term>type and attribute IRIs (redirect to the page; to the vocabulary for JSON-LD clients)
/mapping/<subject>/<Type>/<name>.yamlmapping file (correspondence to another standard and conversion rules; not versioned: the URL stays, the content follows the current model)
/adapters/<name>/<subject>/<Type>.<ext>adapter files: CSV template (.csv), Table Schema (.tableschema.json), structured output for AI (.ai.json), PostgreSQL / PostGIS table (.sql), GeonicDB Custom Data Model definition (.json)
/catalog.jsonlist of all models for programs (conforms to /catalog.schema.json)

Everything is served with Access-Control-Allow-Origin: *; .jsonld files as application/ld+json, schemas as application/schema+json, mapping files as application/yaml, CSV templates as text/csv, SQL files as application/sql, and other .json files (examples, adapter files, catalog.json) as application/json.