English
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
| Purpose | URL |
|---|---|
@context of stored data, Link header | version alias /context/<subject>/v1.jsonld |
| Audits, reproducing a result on another broker | exact 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).
The promises
- A published versioned file is never changed or removed.
/context/<subject>/v1.0.0.jsonldstays 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. - The meaning of an attribute never changes. When it must, the catalog adds a new attribute and marks the old one deprecated.
- Type and attribute IRIs lead to documentation. Opening
https://datamodels.jp/ns/transportation/RoadRestrictionin 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:
| Change | Number | Example |
|---|---|---|
| A fix that changes neither meaning nor validation | patch (1.0.1) | a typo in a schema description |
| A compatible addition | minor (1.1.0) | a new optional attribute or model, a new allowed value |
| An incompatible change | major (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.jsonname 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>.jsonldvocab.jsonld:/vocab/<subject>/v<version>.jsonldschema/<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
| URL | What it is |
|---|---|
/context/<subject>/vX.Y.Z.jsonld | @context (immutable) |
/context/<subject>/vX.jsonld | version alias (latest X.y.z) |
/schema/<subject>/<Type>/vX.Y.Z.json | JSON Schema (immutable) |
/schema/<subject>/<Type>/vX.json | version alias |
/vocab/<subject>/vX.Y.Z.jsonld | vocabulary (RDFS: classes, subclass relations, ja/en labels; immutable) |
/vocab/<subject>/vX.jsonld | version alias |
/examples/<subject>/<Type>/example.json | example (key-values form) |
/examples/<subject>/<Type>/example-normalized.jsonld | example (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>.yaml | mapping 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.json | list 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.