Modular‘s Entity model allows for the storage and retrieval of an Entity’s data that adheres to a specific contract used to translate content to and from structured data. The contract for a view of the structured data is identified by a key for a type that can be any string value. Generally the keys are URLs or a reverse-DNS string that signals who owns the contract and where to find its definition.
The translation between an Entity‘s raw content and it’s structured data is a run-time construct. An Entity's FIDL interface allows access to raw content for a given type but the decoding of that data happens within the client process. How an Entity client decodes and encodes structured data is not enforced directly at the FIDL interfaces.
It's important to note that Entity clients using the same type key expect the structured data to have the same exact contract. Versioning is not directly supported but versioning information can be added to the type key if needed. When versioning is required the following pattern might be useful.
For projects in the
//topaz layer most of the contracts for structured Entity data are implemented as library code available in
For in tree development new, public contracts (schemas & codecs) should be added to this location unless there is a strong case for the contracts to be tied to an app or vendor. Centralizing the definition of these contracts this way helps prevent duplication and divergent implementations.
Topaz‘s schema Dart library exposes codecs that can be instantiated and used with Entity interactions enabled via the ModuleDriver. If a Module or Agent written in Dart needs to read or write Entity data it should use the codec for the correct type to ensure compatibility between components. When reading an Entity’s content, codecs expose structured data wrapped in an instance of an EntityData class holding primitive Dart types, e.g.
Contracts for structured data that is not expected to be exposed as a system level, public type but still needs to be shared should be added to the project's code as a package:
Type keys (URLs, reverse-DNS strings, mime, etc.) MUST be unique and should obviously belong to the vendor:
Tips for adding new schemas:
//topaz/public/lib/schemasor the appropriate location as described above.