{"id":"linked-art/partitioning","relativePath":"linked-art/partitioning.md","title":"Linked Art Graph Partitioning","markdown":"# Linked Art Graph Partitioning\n\nMeta Museum now has a reusable partition planner for the hard case where a\nvalid Linked Art graph needs to be emitted as discrete Linked Art API endpoint\ndocuments.\n\nThe implementation lives in `src/utils/linked-art-partitioner.ts` and is covered\nby `tests/utils/linked-art-partitioner.test.ts`.\n\n## Policy\n\n- First-class endpoint nodes (`HumanMadeObject`, `Person`, `Group`, `Place`,\n `Type`, `Set`, `Activity`, `Event`, `ProvenanceActivity`, textual/visual works,\n and related Linked Art endpoint classes) become their own documents.\n- Cross-document relationships become compact references with `id`, `type`, and\n `_label`, rather than recursively embedding a whole graph.\n- Owned embedded structures remain embedded where Linked Art expects them, such\n as names, dimensions, timespans, provenance `part[]` activities, and lifecycle\n activity summaries.\n- Dereferenceable embedded activity/shared-structure nodes receive\n `_complete: false` through the existing completeness projection policy.\n- Recursive relationships such as object `part`/`part_of`, set `member`/\n `member_of`, concept `broader`, and provenance activity `part[]` are bounded\n with depth and visited-node checks.\n- When the same URI appears as both a compact nested reference and a richer\n graph node, the planner keeps the richer occurrence for the partition document.\n\n## Evidence Fixtures\n\nThe regression suite covers:\n\n- Recursive physical-object parts.\n- Reused activity nodes that are embedded as summaries and also emitted as full\n event/activity documents.\n- Archival set hierarchy and concept `broader`/`member_of` recursion.\n- Provenance wrapper activities with embedded acquisition/payment parts and\n referenced participants.\n- Optional official Linked Art endpoint JSON Schema validation on generated\n partition documents.\n\n## Current Boundary\n\nThe first production adoption paths are:\n\n- `/api/events/{id}` for ActivityStreams `linkedArt.id` dereferences. Activity\n subclasses such as `Production` are routed through the Event/Activity endpoint\n family, and relationships such as `used_specific_object`, `carried_out_by`,\n and `produced` are bounded as compact references when they cross into other\n endpoint documents.\n- `/api/sets/{id}` for stored Set hierarchy records. `member` and `member_of`\n recursion is bounded as compact Set references when the Set is available as a\n stored record. Nested-only referenced sets still fall back to the entity-index\n profile so relation discovery remains available.\n- `/api/concepts/{id}` for stored Concept hierarchy records. `broader` and\n `member_of` recursion is bounded as compact concept/set references while\n preserving the concept endpoint family shape.\n- `/api/objects/{id}` for stored physical object records. Object `part` and\n `part_of` recursion is bounded as compact `HumanMadeObject` references, while\n owned lifecycle summaries such as `produced_by` stay embedded and their\n cross-document actor/place/object relationships stay compact.\n- `/api/records/{id}` for canonical record detail responses. This route runs the\n planner only after it rewrites the stored id to the canonical MetaMuseum detail\n URL and rebuilds `equivalent[]`, then adopts the planner output only for\n sensitive recursive/root-activity fields such as `part`, `part_of`,\n `member_of`, `broader`, and `produced_by`. The broader record-detail envelope\n keeps local metadata such as `_source`, `schemaVersion`, and `_links.self` so\n existing consumers still receive a rich detail record rather than a thin\n endpoint partition.\n\nThis is not yet the universal serialization path for every public route.\nExisting endpoint serializers can adopt it incrementally. The next implementation\nstep is to route additional provider-specific/entity-detail serializers through\nthe same helper style only where planner output reduces duplicate case-by-case\nrecursion logic without weakening their public response contracts.\n","sections":[{"level":2,"heading":"Policy","anchor":"policy"},{"level":2,"heading":"Evidence Fixtures","anchor":"evidence-fixtures"},{"level":2,"heading":"Current Boundary","anchor":"current-boundary"}],"html":"

Linked Art Graph Partitioning

\n

Meta Museum now has a reusable partition planner for the hard case where a

\n

valid Linked Art graph needs to be emitted as discrete Linked Art API endpoint

\n

documents.

\n

The implementation lives in `src/utils/linked-art-partitioner.ts` and is covered

\n

by `tests/utils/linked-art-partitioner.test.ts`.

\n

Policy

\n

`Type`, `Set`, `Activity`, `Event`, `ProvenanceActivity`, textual/visual works,

\n

and related Linked Art endpoint classes) become their own documents.

\n

`_label`, rather than recursively embedding a whole graph.

\n

as names, dimensions, timespans, provenance `part[]` activities, and lifecycle

\n

activity summaries.

\n

`_complete: false` through the existing completeness projection policy.

\n

`member_of`, concept `broader`, and provenance activity `part[]` are bounded

\n

with depth and visited-node checks.

\n

graph node, the planner keeps the richer occurrence for the partition document.

\n\n

Evidence Fixtures

\n

The regression suite covers:

\n

event/activity documents.

\n

referenced participants.

\n

partition documents.

\n\n

Current Boundary

\n

The first production adoption paths are:

\n

subclasses such as `Production` are routed through the Event/Activity endpoint

\n

family, and relationships such as `used_specific_object`, `carried_out_by`,

\n

and `produced` are bounded as compact references when they cross into other

\n

endpoint documents.

\n

recursion is bounded as compact Set references when the Set is available as a

\n

stored record. Nested-only referenced sets still fall back to the entity-index

\n

profile so relation discovery remains available.

\n

`member_of` recursion is bounded as compact concept/set references while

\n

preserving the concept endpoint family shape.

\n

`part_of` recursion is bounded as compact `HumanMadeObject` references, while

\n

owned lifecycle summaries such as `produced_by` stay embedded and their

\n

cross-document actor/place/object relationships stay compact.

\n

planner only after it rewrites the stored id to the canonical MetaMuseum detail

\n

URL and rebuilds `equivalent[]`, then adopts the planner output only for

\n

sensitive recursive/root-activity fields such as `part`, `part_of`,

\n

`member_of`, `broader`, and `produced_by`. The broader record-detail envelope

\n

keeps local metadata such as `_source`, `schemaVersion`, and `_links.self` so

\n

existing consumers still receive a rich detail record rather than a thin

\n

endpoint partition.

\n\n

This is not yet the universal serialization path for every public route.

\n

Existing endpoint serializers can adopt it incrementally. The next implementation

\n

step is to route additional provider-specific/entity-detail serializers through

\n

the same helper style only where planner output reduces duplicate case-by-case

\n

recursion logic without weakening their public response contracts.

","updatedAt":"2018-10-20T01:46:40.000Z","checksum":"341aff71f753fa6ff99798603baa9af76314629e20560e7a1750b948a1d9b8b8","checksumPrefix":"341aff71f753","anchorCount":3,"lineCount":75,"rawUrl":"/api/docs/content?path=linked-art%2Fpartitioning.md","htmlUrl":"/docs?doc=linked-art%2Fpartitioning.md","apiUrl":"/api/docs/content?path=linked-art%2Fpartitioning.md"}