MASL — Metadata for Arbitrary Structures & Links

Introduction

Anywhere you have resources that will be deployed in real-world systems, the potential metadata needs of those systems are effectively unbounded. Designing or constraining a syntax for all metadata needs would be hubris and madness. Instead, this document tries to minimally constrain applications while illustrating "where to stick" that metadata, as there are so few layers and hiding places in the DASL system.

The recommended structure for DASL metadata is to insert a dCBOR42 document "between" each CID and its resource(s), essentially using dCBOR42 as headers wrapping a CID-addressed resource. To do this, simply replace a CID of a resource with a CID to a dCBOR42 document that contains either a top-level [type 42] property src (for a single resource), containing the CID of the resource it describes, or a top-level mapping resources (for a collection of resources), mapping paths to resource CIDs, each with optional dCBOR42 metadata ([cid], [dcbor42]).

How to use a MASL document

It is preferable to nest any metadata in a top-level object to namespace your own metadata standard (inside an object named, for example, `my-cool-project-v1`) rather than opaque version-bits or magic numbers. There are a few reserved words at the top-level, but these can be avoided by nesting any conflicts.

There are many metadata standards that can be embedded in this way to facilitate the preservation of metadata at ingress as well as translatability. For example, the IPFS-based storage system Storacha has a robust CID-based metadata system called content credentials which includes UCAN-based permissioning and CID "equivalence," i.e. one or more IPFS CIDs equivalent to given DASL CID.

Reserved words: HTTP headers

HTTP use cases use best served by setting a HTTP headers per resourcej. What follows is a list of lowercase top-level properties and the HTTP headers they map to, as well as constraints on values for them:

• content-type: Content-Type. No constraints.
...

No other HTTP headers should be encoded into MASL documents for RASL purposes if wide interoperability is expected.

Reserved words: Previous Version Chaining

In addition to resources, src, and the HTTP header values mentioned above, there is a final reserved word for refering to the previous version of an updated MASL document by CID. This value is called prv, and can be used to create verifiable chains of mutated documents.

Collections are not Directories

As DASL is not a "file system" it does not have a concept isomorphic to directories or "folders"; there is, however, the RASL concept of a transport-agnostic collection, for which a MASL metadata document can be used to describe a service or behavior. In such a usage, the resources mapping contains, in addition to an identifer --> CID mapping, additional metadata properties that would be at the top level in a single-CID MASL file, including the src property containing that CID. (The isomorphism here is to a web service, which maps URIs to resources arbitrarily, and can map multiple paths or filenames to the same resource).

TODO: Example codeblock

Note: a MASL document containing both a top-level resources mapping and a top-level src should be considered malformed, and resources should be treated as canonical over a src if both are present.

References

[cid]

Robin Berjon & Juan Caballero. Content IDs (CIDs). 2025-02-05. URL: https://dasl.ing/cid.html

[dcbor42]

Robin Berjon & Juan Caballero. Deterministic CBOR with tag 42 (dCBOR42). 2025-02-05. URL: https://dasl.ing/dcbor42.html