Architectural trajectory
The capabilities below are not yet implemented in production in the form described. They represent the architectural direction of the framework, informed by both prior research and the requirements of Graviola's existing users. Each is documented so that current development decisions remain compatible with these directions.
The discipline applied to this section: a capability is described here only when its shape is clear enough that the team has chosen not to foreclose it through current design choices.
For what ships today, see Capabilities today.
Authoring versus trajectory: build-time modeling choices (for example generating JSON Schema and UI schema from LinkML as an authoring source for schemas) are separate from the capabilities below. LinkML is an optional application build step; it does not move unfinished runtime features into production.
Generative tooling versus trajectory: assistance that drafts or refines schemas, forms, and mappings (see Graviola in the age of generative tools) attaches to the same declarative surfaces Graviola already uses; it does not substitute for the runtime capabilities sketched below.
Vocabulary note: the Store interface in @graviola/store-core (capability facets + CapabilityDescriptor) is current reality. The term AbstractDatastore is legacy in new material; trajectory extensions are expressed as new capability facets, descriptor extensions, and ReadResult envelope extensions — not as methods on a monolithic interface.
Detailed trajectory chapters
The topics below have dedicated chapters with design detail, invariants, and examples:
| Topic | Chapter | Status |
|---|---|---|
| Scope-keyed sidecars (UI, calc, meta) | The sidecar pattern | UI schema: production; calc + MetaSchema: proposed |
| Calculated fields, stratification, compilation | Calculated fields | Proposed / partially designed |
Lenses, writable computeds, x-inverseOf retirement | Lenses and bidirectional transforms | Proposed |
| Fact-level and entity-level metadata | Provenance and metadata | Proposed |
| Federation registry, composites, CBD-cut | Store topology | Proposed |
Schema evolution via lenses
Schemas evolve over the lifetime of an application. In Graviola's current deployments, this is handled either by classical migration scripts (where the application owns its database) or by manual rewriting of mapping configurations (where data is ingested from a versioned authority).
The architectural direction is to express version-to-version transformations as bidirectional lenses — small, composable, declarative documents that describe how to migrate data forward to a newer schema and, where possible, backward to an older one. This is a well-studied pattern; the closest existing implementation is Project Cambria from Ink & Switch.
In Graviola's intended model, each entity carries a gra:version property identifying the schema version under which it was authored. A consumer encountering an entity at a different version applies the appropriate lens chain at query time. The lens engine is an opt-in capability of a Store implementation, not a requirement.
The July 2026 design session reframes lenses as the unifying concept behind inverse properties, writable computeds, reversible mappings, and version migrations — see Lenses and bidirectional transforms.
Related glossary entries: Lens, Entity version, Schema drift, Lens-as-data.
Calculated fields
Some schema properties are best expressed as derivations rather than stored values. The intended mechanism is a declarative formula language with dependency graphs, auth/completeness stratification, and capability-aware evaluation placement.
See Calculated fields for the full design: defaults ladder, calc profile sidecar, compilation and stratification, and the compile/runtime invariants.
Related glossary entries: Calculated field, Capability context, Stratification, Compiled profile.
Provenance and administrative metadata
Beyond pipeline-level provenance in read results, the trajectory adds statement-level metadata (Wikidata-model $stmt siblings) and entity-level $meta (framework-guaranteed on all backends). Both integrate via The sidecar pattern and pure Layer-1 schema derivations.
Store federation and topology
Multiple stores — authoritative triple stores, derived search indexes, read-only application translators — are intended to register behind a federation layer with explicit dimensions (authority, derivability, shape fidelity) and composite stores that hide boundaries cutting through an entity.
See Store topology.
Signed states and authoritative value
For applications where the credibility of data matters — historical databases, cultural heritage catalogs, expert-curated reference works — the framework's intended trust model is built on signed states: cryptographically signed snapshots of an entity (or of a lens, or of a schema) attesting that a named party vouches for its correctness at a moment in time. Multiple signatures, weighted by the trust graph among signers, contribute to a computed authoritative value used to surface plausible versus contested entries.
The cryptographic substrate is intended to be the W3C Verifiable Credentials Data Model.
Related glossary entries: Signed state, Authoritative value.
Schema and lens as syncable data
Graviola's existing storage layer treats data as documents. The intended extension is to treat schemas and lenses themselves as documents — JSON-LD documents with stable @ids, syncing through the same transport (Yjs, Solid, SPARQL endpoints) as application data. This generalizes a pattern observed in field deployments where domain experts authored schemas via JSON Forms-based designers and distributed them peer-to-peer alongside the data.
When schemas, lenses, and data all flow through one transport, signing extends uniformly to all three. MetaSchema extends the same pattern to administrative metadata documents.
Related glossary entries: Schema-as-data, Federated sync layer, MetaSchema.
See also
- The sidecar pattern — cross-cutting structural convention.
- Deployment scenarios — where trajectory topics intersect real deployments.
- LinkML as an authoring source for schemas — optional upstream authoring; runtime trajectory unchanged.
- Outlook and open questions — unresolved design tensions at the frontier.
- Glossary — definitions and references in one place.
- Further reading.