{"id":"linked-art/api/json-ld-considerations","relativePath":"linked-art/api/json-ld-considerations.md","title":"Linked Art API: JSON-LD Considerations","markdown":"# Linked Art API: JSON-LD Considerations\n\n**Last refreshed:** 2026-07-06\n\nSource: [JSON-LD Considerations](https://linked.art/api/1.0/json-ld/), part of Linked Art API 1.0, published under [CC BY 4.0](http://creativecommons.org/licenses/by/4.0/). This is a project summary; the upstream page is authoritative.\n\n## Purpose\n\nLinked Art API records use JSON-LD so publishers can expose Linked Open Data while keeping responses usable as predictable JSON for ordinary backend and browser clients. The context maps compact JSON keys to RDF predicates and classes, letting implementers work with stable JSON object shapes without requiring RDF tooling for basic consumption.\n\nThe canonical Linked Art context is:\n\n```text\nhttps://linked.art/ns/v1/linked-art.json\n```\n\nStandalone Linked Art API records should carry this context in `@context`. Embedded structures inherit the containing record's context unless they are shared separately as Linked Art JSON-LD.\n\n## Media Type\n\nThe Linked Art JSON-LD media type profile is:\n\n```text\napplication/ld+json;profile=\"https://linked.art/ns/v1/linked-art.json\"\n```\n\nPublishers should use it as the `Content-Type` for Linked Art JSON-LD responses. Consumers can send it in `Accept` when a server supports content negotiation. Other serializations may exist, but the Linked Art API does not require consumers to assume Turtle, RDF/XML, or any other graph serialization is available.\n\n## Core JSON-LD Rules\n\n- Terms are case sensitive. `Type` and `type` are different keys with different meanings.\n- Properties cannot be repeated within a JSON object. Multi-valued Linked Art properties stay arrays, even when only one value is present.\n- Linked Art uses serialization order for ordered values where needed; it does not require RDF ordered lists for normal API records.\n- `id` and `type` are JSON-LD-friendly aliases for `@id` and `@type`.\n- `_label` is a developer-facing label and should not be treated as the canonical public display name when structured names are available.\n- Consumers should preserve unknown but valid extension data where their own contracts allow it, but schema-bound endpoint checks can still reject unexpected top-level fields when validating strict API shapes.\n\n## Context Design\n\nThe Linked Art context is designed to make the JSON ergonomic without losing CIDOC-CRM semantics:\n\n- Class names use upper CamelCase, such as `HumanMadeObject`.\n- Property names use lower snake_case, such as `identified_by`.\n- Namespace prefixes and CRM numeric prefixes are hidden behind the context.\n- Dashes are removed from class names so keys remain easy to use in common programming languages.\n- Inconsistent or colliding ontology predicates are normalized to practical API keys.\n- Common partitioning relationships are presented as `part` and `part_of` where scoped contexts can preserve the precise underlying RDF predicate.\n- The context includes common ontology and vocabulary prefixes, including RDF, SKOS, schema.org, AAT, TGN, and GeoNames patterns.\n\nThe important implementation consequence is simple: JSON keys should be treated as Linked Art API terms, not as raw CIDOC-CRM property names. If a transformation needs graph precision, expand through the context rather than inventing local key mappings.\n\n## Plain JSON Usability\n\nLinked Art deliberately makes records usable by JSON clients:\n\n- Client code can read `id`, `type`, `identified_by`, `classified_as`, `equivalent`, `part`, `part_of`, and other fields directly.\n- Basic API consumers should not need JSON-LD expansion or SPARQL to display or traverse records.\n- RDF-aware consumers can still expand the same JSON-LD into graph data for validation, reasoning, or triplestore loading.\n\nThis is the bridge we care about in Meta Museum: human-facing product code can use predictable JSON structures, while conformance checks can still prove the records expand to linked data.\n\n## Meta Museum Notes\n\nMeta Museum already relies on these rules: Linked Art JSON-LD is canonical at record boundaries, HAL `_links` stay outside semantic graph assertions, multi-valued properties remain arrays, URI handling stays opaque, and SHACL/schema checks validate the linked-data shape instead of relying on display-only DTOs.\n\nThis note should be used whenever code touches API serialization, dataset exports, ActivityStreams embedded `linkedArt` projections, record fixtures, or docs examples. In practice, check that records keep the canonical `@context`, preserve `id` and `type`, avoid repeated JSON properties, keep array-valued fields as arrays, and remain usable as predictable JSON without sacrificing RDF compatibility.\n\n## Test Ideas\n\n- Assert public records and exports include `@context: \"https://linked.art/ns/v1/linked-art.json\"` where they are standalone Linked Art JSON-LD.\n- Keep `id` and `type` aliases stable instead of leaking `@id`/`@type` into project-authored API records.\n- Preserve array-valued fields such as `identified_by`, `classified_as`, `equivalent`, `part`, and `part_of` at cardinality 1.\n- Reject accidental case drift such as `Type` where `type` is required, or `type` where a `Type` class reference is required.\n- Verify JSON-LD fixtures remain usable by ordinary JSON consumers and expandable by RDF/SHACL validation tooling.\n","sections":[{"level":2,"heading":"Purpose","anchor":"purpose"},{"level":2,"heading":"Media Type","anchor":"media-type"},{"level":2,"heading":"Core JSON-LD Rules","anchor":"core-json-ld-rules"},{"level":2,"heading":"Context Design","anchor":"context-design"},{"level":2,"heading":"Plain JSON Usability","anchor":"plain-json-usability"},{"level":2,"heading":"Meta Museum Notes","anchor":"meta-museum-notes"},{"level":2,"heading":"Test Ideas","anchor":"test-ideas"}],"html":"

Linked Art API: JSON-LD Considerations

\n

Last refreshed: 2026-07-06

\n

Source: JSON-LD Considerations, part of Linked Art API 1.0, published under CC BY 4.0. This is a project summary; the upstream page is authoritative.

\n

Purpose

\n

Linked Art API records use JSON-LD so publishers can expose Linked Open Data while keeping responses usable as predictable JSON for ordinary backend and browser clients. The context maps compact JSON keys to RDF predicates and classes, letting implementers work with stable JSON object shapes without requiring RDF tooling for basic consumption.

\n

The canonical Linked Art context is:

\n
\nhttps://linked.art/ns/v1/linked-art.json\n
\n

Standalone Linked Art API records should carry this context in `@context`. Embedded structures inherit the containing record's context unless they are shared separately as Linked Art JSON-LD.

\n

Media Type

\n

The Linked Art JSON-LD media type profile is:

\n
\napplication/ld+json;profile="https://linked.art/ns/v1/linked-art.json"\n
\n

Publishers should use it as the `Content-Type` for Linked Art JSON-LD responses. Consumers can send it in `Accept` when a server supports content negotiation. Other serializations may exist, but the Linked Art API does not require consumers to assume Turtle, RDF/XML, or any other graph serialization is available.

\n

Core JSON-LD Rules

\n\n

Context Design

\n

The Linked Art context is designed to make the JSON ergonomic without losing CIDOC-CRM semantics:

\n\n

The important implementation consequence is simple: JSON keys should be treated as Linked Art API terms, not as raw CIDOC-CRM property names. If a transformation needs graph precision, expand through the context rather than inventing local key mappings.

\n

Plain JSON Usability

\n

Linked Art deliberately makes records usable by JSON clients:

\n\n

This is the bridge we care about in Meta Museum: human-facing product code can use predictable JSON structures, while conformance checks can still prove the records expand to linked data.

\n

Meta Museum Notes

\n

Meta Museum already relies on these rules: Linked Art JSON-LD is canonical at record boundaries, HAL `_links` stay outside semantic graph assertions, multi-valued properties remain arrays, URI handling stays opaque, and SHACL/schema checks validate the linked-data shape instead of relying on display-only DTOs.

\n

This note should be used whenever code touches API serialization, dataset exports, ActivityStreams embedded `linkedArt` projections, record fixtures, or docs examples. In practice, check that records keep the canonical `@context`, preserve `id` and `type`, avoid repeated JSON properties, keep array-valued fields as arrays, and remain usable as predictable JSON without sacrificing RDF compatibility.

\n

Test Ideas

\n","updatedAt":"2026-07-06T00:00:00.000Z","checksum":"dc542f437a1237047bf86c9b02aca57eba3e25e84a5158e10c66cdd05cd04f27","checksumPrefix":"dc542f437a12","anchorCount":7,"lineCount":75,"rawUrl":"/api/docs/content?path=linked-art%2Fapi%2Fjson-ld-considerations.md","htmlUrl":"/docs?doc=linked-art%2Fapi%2Fjson-ld-considerations.md","apiUrl":"/api/docs/content?path=linked-art%2Fapi%2Fjson-ld-considerations.md"}