RASL, MASL, and Tile lexicons

[ngerakines]

Hello everyone,

I'm working on something that uses RASL, MASL, and tiles, and the lexicons for the types of data they represent. This isn't a formal proposal or change request, but I wanted to show what I'm working with locally and why to see if we can bridge some gaps.

ing.dasl.masl

{
  "lexicon": 1,
  "id": "ing.dasl.masl",
  "description": "MASL types for DASL, notably for Web Tiles.",
  "defs": {
    "bundle": {
      "type": "object",
      "description": "A bundle of named resources.",
      "required": ["resources"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Optional name for the bundle."
        },
        "resources": {
          "type": "unknown",
          "description": "A mapping of resources in this bundle."
        }
      }
    },
    "resource": {
      "type": "object",
      "description": "A single resource identified by a CID.",
      "required": ["src"],
      "properties": {
        "src": {
          "type": "cid-link",
          "description": "The content identifier for this resource."
        },
        "srcHints": {
          "type": "array",
          "description": "Optional hints associated with this resource.",
          "items": {
            "type": "string"
          }
        }
      }
    }
  }
}

The masl lexicon has two object definitions for resource and bundle structures. The resource structure is the single one-off resource that has an explicit path and the rest of the metadata listed on the spec. The bundle structure is a multitude of resources along with the rest of the metadata listed on the spec.

In both case, there are a bunch of fields on both bundles and resources that I'm not proposing are removed, but are omitted for brevity.

The note is that neither of these are "records" in atprotocol because the intention is that they are included in and part of other things that have resources (or resource bundles).

An example resource:

{
  "$type": "ing.dasl.masl#resource",
  "src": { "$link": "bafyreia5v57w4eugbgxtnr73wi6zuqs65ogvy2dlnwkc453oya4llyea3i" }
}

An example bundle:

{
  "$type": "ing.dasl.masl#bundle",
  "name": "my-web-app",
  "resources": {
    "/": {
      "src": { "$link": "bafyreia5v57w4eugbgxtnr73wi6zuqs65ogvy2dlnwkc453oya4llyea3i" },
    },
    "/style.css": {
      "src": { "$link": "bafyreifvpsnkyjsjtcaphw3ofrzjipl5gm6ayz6ku4j62fustet6t5kdce" },
      "srcHints": ["mycdn.com"]
    },
    "/icon.png": {
      "src": { "$link": "bafyreig6tlkldo7zusncxlmcwhchbmbve5vsmmza2dg7ieehrckgucc5da" },
      "srcHints": ["othercdn.com"]
    }
  }
}

Alternative

{
  "lexicon": 1,
  "id": "ing.dasl.masl",
  "description": "MASL types for DASL, notably for Web Tiles. This variant uses a typed resources array.",
  "defs": {
    "bundle": {
      "type": "object",
      "description": "A bundle of resources.",
      "required": ["resources"],
      "properties": {
        "name": {
          "type": "string",
          "description": "Optional name for the bundle."
        },
        "resources": {
          "type": "array",
          "description": "The resources in this bundle.",
          "items": {
            "type": "ref",
            "ref": "ing.dasl.masl#resource"
          }
        }
      }
    },
    "resource": {
      "type": "object",
      "description": "A single resource identified by a CID.",
      "required": ["src"],
      "properties": {
        "path": {
          "type": "string",
          "description": "Optional path for this resource (e.g. '/index.html')."
        },
        "src": {
          "type": "cid-link",
          "description": "The content identifier for this resource."
        },
        "srcHints": {
          "type": "array",
          "description": "Optional hints associated with this resource.",
          "items": {
            "type": "string"
          }
        }
      }
    }
  }
}

I'm not a huge fan of "unknown" and intentionally ambiguous definitions, so I think it's actually worthwhile to adapt this lexicon slightly to conform to current lexicon schema limitations. Instead of having "resources" as an infinitely large object of path keys to resource values, we make resources an array of resource types and add an optional path string field to the resource definition.

This has trade-offs that are worth discussing. The array is strongly typed and creates a way to improve the full and end-to-end validation of MASL documents and the parent records and structures that use them. The compromise is that it makes it possible for someone to create a duplicate resource path entry which should be handled appropriately. I'm not actually convinced that duplicate paths is a bad thing given bundles could service different types of container structures, so but it is a discussion that should be had.

An example of this bundle structure would look like:

{
  "$type": "ing.dasl.masl#bundle",
  "name": "my-web-app",
  "resources": [
    {
      "path": "/",
      "src": { "$link": "bafyreia5..." }
    },
    {
      "path": "/style.css",
      "src": { "$link": "bafyreifv..." },
      "srcHints": ["mycdn.com"]
    }
  ]
}

Tile

{
  "lexicon": 1,
  "id": "ing.dasl.tile",
  "description": "A Web Tile record for DASL.",
  "defs": {
    "main": {
      "type": "record",
      "description": "A tile with a name and associated resource or bundle.",
      "key": "tid",
      "record": {
        "type": "object",
        "required": ["name", "content"],
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of the tile."
          },
          "content": {
            "type": "union",
            "description": "The tile content, either a single resource or a bundle.",
            "refs": [
              "ing.dasl.masl#resource",
              "ing.dasl.masl#bundle"
            ]
          }
        }
      }
    }
  }
}

An example tile with a resource. When a single resource is included then the path is automatically "/".

{
  "$type": "ing.dasl.tile",
  "name": "Hello World",
  "content": {
    "$type": "ing.dasl.masl#resource",
    "src": { "$link": "bafyreia5v57w4eugbgxtnr73wi6zuqs65ogvy2dlnwkc453oya4llyea3i" }
  }
}

An example tile with a bundle.

{
  "$type": "ing.dasl.tile",
  "name": "My Web App",
  "content": {
    "$type": "ing.dasl.masl#bundle",
    "name": "my-web-app",
    "resources": {
      "/": {
        "src": { "$link": "bafyreia5v57w4eugbgxtnr73wi6zuqs65ogvy2dlnwkc453oya4llyea3i" }
      },
      "/style.css": {
        "src": { "$link": "bafyreifvpsnkyjsjtcaphw3ofrzjipl5gm6ayz6ku4j62fustet6t5kdce" },
        "srcHints": ["mycdn.com"]
      },
      "/icon.png": {
        "src": { "$link": "bafyreig6tlkldo7zusncxlmcwhchbmbve5vsmmza2dg7ieehrckgucc5da" },
        "srcHints": ["did:web:example.com#atproto_pds"]
      }
    }
  }
}

And with the bundle-array variant:

{
  "$type": "ing.dasl.tile",
  "name": "My Web App",
  "content": {
    "$type": "ing.dasl.masl#bundle",
    "name": "my-web-app",
    "resources": [
      {
        "path": "/",
        "src": { "$link": "bafyreia5..." }
      },
      {
        "path": "/style.css",
        "src": { "$link": "bafyreifv..." },
        "srcHints": ["mycdn.com"]
      }
    ]
  }
}

[darobin]

I think that bringing RASL into MASL is definitely interesting and something we should consider.

I'm less sure about shoehorning resources into what lexicons currently support. I totally get the argument that it's better to have it defined, I don't disagree, but the way I look at it type systems should support people in doing what they need to do, not the other way around! I did consider using an array but this would require a de-deduplication rule (as you mention) and the first thing that almost any implementation would do is load that array into a map. So all that this buys is additional risk of impedance mismatch and round-tripping failures. Not a huge deal, manageable, but the bug here is on lexicon more than on DASL.

I haven't tracked lexicon discussions closely, but is there a known reason why this pretty typical pattern isn't supported? It would be pretty easy to add a map type with types for keys and values.