♻️ Move block lexicon defs to reusable namespace (#48)

* ♻️ Move block lexicon defs to reusable namespace

Place block type definitions in `pub.oxa.blocks.defs` and generate them at `lexicon/blocks/defs.json` instead of nesting them under the document lexicon. Update generated refs, conversion code, tests, docs, and examples to use the new block namespace.\n\nThis makes the block schema easier to reuse from other document lexicons rather than tying it to `pub.oxa.document.document`. For example, `pub.oxa.blocks.defs#block` can be referenced from an open `content` property in another record schema such as `site.standard.document`.\n\nCo-authored-by: Stencila <47797644+stencila[bot]@users.noreply.github.com>

* chore(*): update formatted/generated files [skip ci]

* ♻️ Simplify document lexicon id to `pub.oxa.document`

Simplify the document record NSID from `pub.oxa.document.document` to
`pub.oxa.document`, consistent with the naming convention used by
`site.standard.document` and others. This is possible now that block
type definitions have been moved to their own `pub.oxa.blocks.defs`
namespace.

Co-authored-by: Stencila <47797644+stencila[bot]@users.noreply.github.com>

* chore(*): update formatted/generated files [skip ci]

* Move generated file

---------

Co-authored-by: Stencila <47797644+stencila[bot]@users.noreply.github.com>

Author: nokome

docs/atproto-lexicon.md

@@ -19,12 +19,12 @@ By defining a lexicon, OXA documents become first-class objects on the AT Protoc
 
 ## Lexicon structure
 
-The OXA lexicon is organized into two namespaces:
+The OXA lexicon is organized into three namespaces:
 
 | File                             | NSID                        | Purpose                                                                                 |
 | -------------------------------- | --------------------------- | --------------------------------------------------------------------------------------- |
-| `lexicon/document/document.json` | `pub.oxa.document.document` | The `Document` record type — the root object stored in a PDS                            |
-| `lexicon/document/defs.json`     | `pub.oxa.document.defs`     | Block-level type definitions (`paragraph`, `heading`, `richText`) and the `block` union |
+| `lexicon/document/document.json` | `pub.oxa.document` | The `Document` record type — the root object stored in a PDS                            |
+| `lexicon/blocks/defs.json`       | `pub.oxa.blocks.defs`       | Block-level type definitions (`paragraph`, `heading`, `richText`) and the `block` union |
 | `lexicon/richtext/facet.json`    | `pub.oxa.richtext.facet`    | Facet annotations for inline formatting (`emphasis`, `strong`, `byteSlice`)             |
 
 A `Document` record contains an array of `children` (blocks). Each block carries a `text` string and an optional `facets` array that annotates ranges of that text with formatting features.
@@ -112,7 +112,7 @@ AT Protocol [uses facets instead of a tree](https://www.pfrazee.com/blog/why-fac
 
 ```json
 {
-  "$type": "pub.oxa.document.defs#paragraph",
+  "$type": "pub.oxa.blocks.defs#paragraph",
   "text": "This is bold and italic text.",
   "facets": [
     {
@@ -201,16 +201,16 @@ Produces:
 
 ```json
 {
-  "$type": "pub.oxa.document.document",
+  "$type": "pub.oxa.document",
   "children": [
     {
-      "$type": "pub.oxa.document.defs#heading",
+      "$type": "pub.oxa.blocks.defs#heading",
       "level": 1,
       "text": "Hello",
       "facets": []
     },
     {
-      "$type": "pub.oxa.document.defs#paragraph",
+      "$type": "pub.oxa.blocks.defs#paragraph",
       "text": "Some emphasized text.",
       "facets": [
         {
@@ -265,8 +265,8 @@ The lexicon files are generated from the OXA YAML schema definitions by the code
 1. Loads the merged OXA JSON Schema.
 2. Classifies each type as inline or block based on the `Inline` and `Block` union definitions.
 3. Maps inline types to facet features in `pub.oxa.richtext.facet` (excluding `Text`, which becomes the plain text string).
-4. Maps block types to object definitions in `pub.oxa.document.defs`, replacing their inline `children` arrays with `text` + `facets` pairs.
-5. Emits the `Document` record type in `pub.oxa.document.document`.
+4. Maps block types to object definitions in `pub.oxa.blocks.defs`, replacing their inline `children` arrays with `text` + `facets` pairs.
+5. Emits the `Document` record type in `pub.oxa.document`.
 
 To regenerate the lexicon after changing the schema:
 

examples/rfc0003.atproto.json

@@ -1,5 +1,5 @@
 {
-  "$type": "pub.oxa.document.document",
+  "$type": "pub.oxa.document",
   "title": {
     "text": "Water Dissociation: H2O → H+ + OH−",
     "facets": [
@@ -19,13 +19,13 @@
   },
   "children": [
     {
-      "$type": "pub.oxa.document.defs#heading",
+      "$type": "pub.oxa.blocks.defs#heading",
       "text": "Introduction",
       "facets": [],
       "level": 1
     },
     {
-      "$type": "pub.oxa.document.defs#paragraph",
+      "$type": "pub.oxa.blocks.defs#paragraph",
       "text": "Water (H2O) undergoes autoionization, a process in which a water molecule donates a proton to another. The equilibrium constant for this reaction, Kw, is approximately 10−14 at 25 °C.",
       "facets": [
         {
@@ -50,15 +50,15 @@
         }
       ]
     },
-    { "$type": "pub.oxa.document.defs#thematicBreak" },
+    { "$type": "pub.oxa.blocks.defs#thematicBreak" },
     {
-      "$type": "pub.oxa.document.defs#heading",
+      "$type": "pub.oxa.blocks.defs#heading",
       "text": "Computing the Equilibrium",
       "facets": [],
       "level": 2
     },
     {
-      "$type": "pub.oxa.document.defs#paragraph",
+      "$type": "pub.oxa.blocks.defs#paragraph",
       "text": "The following Python snippet computes Kw from ion concentrations:",
       "facets": [
         {
@@ -68,12 +68,12 @@
       ]
     },
     {
-      "$type": "pub.oxa.document.defs#code",
+      "$type": "pub.oxa.blocks.defs#code",
       "value": "H_plus = 1e-7   # mol/L\nOH_minus = 1e-7  # mol/L\nKw = H_plus * OH_minus\nprint(f\"Kw = {Kw:.2e}\")  # Kw = 1.00e-14",
       "language": "python"
     },
     {
-      "$type": "pub.oxa.document.defs#paragraph",
+      "$type": "pub.oxa.blocks.defs#paragraph",
       "text": "You can run this with python kw.py. The result confirms the well-known value of Kw.",
       "facets": [
         {
@@ -90,15 +90,15 @@
         }
       ]
     },
-    { "$type": "pub.oxa.document.defs#thematicBreak" },
+    { "$type": "pub.oxa.blocks.defs#thematicBreak" },
     {
-      "$type": "pub.oxa.document.defs#heading",
+      "$type": "pub.oxa.blocks.defs#heading",
       "text": "Summary",
       "facets": [],
       "level": 2
     },
     {
-      "$type": "pub.oxa.document.defs#paragraph",
+      "$type": "pub.oxa.blocks.defs#paragraph",
       "text": "This example demonstrates every node type from RFC0003: Heading, Paragraph, Code, ThematicBreak, Text, Emphasis, Strong, Superscript, Subscript, and InlineCode.",
       "facets": [
         {

lexicon/document/defs.json lexicon/blocks/defs.jsonlexicon/document/defs.json renamed to lexicon/blocks/defs.json

@@ -1,6 +1,6 @@
 {
   "lexicon": 1,
-  "id": "pub.oxa.document.defs",
+  "id": "pub.oxa.blocks.defs",
   "defs": {
     "richText": {
       "type": "object",

lexicon/document/document.json lexicon/document.jsonlexicon/document/document.json renamed to lexicon/document.json

@@ -1,6 +1,6 @@
 {
   "lexicon": 1,
-  "id": "pub.oxa.document.document",
+  "id": "pub.oxa.document",
   "defs": {
     "main": {
       "type": "record",
@@ -26,13 +26,13 @@
           },
           "title": {
             "type": "ref",
-            "ref": "pub.oxa.document.defs#richText"
+            "ref": "pub.oxa.blocks.defs#richText"
           },
           "children": {
             "type": "array",
             "items": {
               "type": "ref",
-              "ref": "pub.oxa.document.defs#block"
+              "ref": "pub.oxa.blocks.defs#block"
             }
           },
           "createdAt": {

packages/oxa-core/src/convert.test.ts

@@ -26,11 +26,11 @@ const lexiconFiles = {
     path: resolve(REPO_ROOT, "lexicon/richtext/facet.json"),
   },
   defs: {
-    id: "pub.oxa.document.defs",
-    path: resolve(REPO_ROOT, "lexicon/document/defs.json"),
+    id: "pub.oxa.blocks.defs",
+    path: resolve(REPO_ROOT, "lexicon/blocks/defs.json"),
   },
   document: {
-    id: "pub.oxa.document.document",
+    id: "pub.oxa.document",
     path: resolve(REPO_ROOT, "lexicon/document/document.json"),
   },
 } as const;
@@ -342,9 +342,9 @@ describe("ATProto lexicon structure", () => {
     expect(main.type).toBe("record");
     expect(main.key).toBe("tid");
     expect(record.required).toEqual(["children", "createdAt"]);
-    expect(record.properties.title.ref).toBe("pub.oxa.document.defs#richText");
+    expect(record.properties.title.ref).toBe("pub.oxa.blocks.defs#richText");
     expect(record.properties.children.items.ref).toBe(
-      "pub.oxa.document.defs#block",
+      "pub.oxa.blocks.defs#block",
     );
     expect(record.properties.createdAt).toEqual({
       type: "string",
@@ -380,7 +380,7 @@ describe("mapBlock", () => {
     );
 
     await expect(map(block)).resolves.toEqual({
-      $type: "pub.oxa.document.defs#paragraph",
+      $type: "pub.oxa.blocks.defs#paragraph",
       id: "para-1",
       classes: ["lead"],
       data: { align: "left" },
@@ -405,7 +405,7 @@ describe("mapBlock", () => {
     });
 
     await expect(map(block)).resolves.toEqual({
-      $type: "pub.oxa.document.defs#heading",
+      $type: "pub.oxa.blocks.defs#heading",
       id: "intro",
       classes: ["hero"],
       data: { section: true },
@@ -470,7 +470,7 @@ describe("oxaToAtproto", () => {
     );
 
     await expect(convertDocument(document, { createdAt })).resolves.toEqual({
-      $type: "pub.oxa.document.document",
+      $type: "pub.oxa.document",
       title: {
         text: "Hello, World",
         facets: [],
@@ -481,13 +481,13 @@ describe("oxaToAtproto", () => {
       },
       children: [
         {
-          $type: "pub.oxa.document.defs#heading",
+          $type: "pub.oxa.blocks.defs#heading",
           level: 1,
           text: "Introduction",
           facets: [],
         },
         {
-          $type: "pub.oxa.document.defs#paragraph",
+          $type: "pub.oxa.blocks.defs#paragraph",
           text: "This is bold and italic text.",
           facets: [
             {
@@ -517,7 +517,7 @@ describe("oxaToAtproto", () => {
     await expect(
       convertDocument(documentNode([]), { createdAt }),
     ).resolves.toEqual({
-      $type: "pub.oxa.document.document",
+      $type: "pub.oxa.document",
       children: [],
       createdAt,
     });
@@ -551,11 +551,11 @@ describe("oxaToAtproto", () => {
     );
 
     expect(converted).toEqual({
-      $type: "pub.oxa.document.document",
+      $type: "pub.oxa.document",
       metadata,
       children: [
         {
-          $type: "pub.oxa.document.defs#paragraph",
+          $type: "pub.oxa.blocks.defs#paragraph",
           text: "Keep this paragraph",
           facets: [],
         },

packages/oxa-core/src/convert.ts

@@ -96,23 +96,23 @@ interface RichText {
 
 type AtprotoParagraph = RichText &
   BlockNodeBase & {
-    $type: "pub.oxa.document.defs#paragraph";
+    $type: "pub.oxa.blocks.defs#paragraph";
   };
 
 type AtprotoHeading = RichText &
   BlockNodeBase & {
-    $type: "pub.oxa.document.defs#heading";
+    $type: "pub.oxa.blocks.defs#heading";
     level: number;
   };
 
 type AtprotoCode = BlockNodeBase & {
-  $type: "pub.oxa.document.defs#code";
+  $type: "pub.oxa.blocks.defs#code";
   value: string;
   language?: string;
 };
 
 type AtprotoThematicBreak = BlockNodeBase & {
-  $type: "pub.oxa.document.defs#thematicBreak";
+  $type: "pub.oxa.blocks.defs#thematicBreak";
 };
 
 type AtprotoBlock =
@@ -122,7 +122,7 @@ type AtprotoBlock =
   | AtprotoThematicBreak;
 
 type AtprotoDocument = {
-  $type: "pub.oxa.document.document";
+  $type: "pub.oxa.document";
   title?: RichText;
   metadata?: Record<string, unknown>;
   children: AtprotoBlock[];
@@ -184,10 +184,10 @@ export const compatibleFeatures: Record<
 
 const formattingPropertyNames = ["id", "classes", "data"] as const;
 const blockPropertyNames = ["id", "classes", "data"] as const;
-const paragraphType = "pub.oxa.document.defs#paragraph" as const;
-const headingType = "pub.oxa.document.defs#heading" as const;
-const codeType = "pub.oxa.document.defs#code" as const;
-const thematicBreakType = "pub.oxa.document.defs#thematicBreak" as const;
+const paragraphType = "pub.oxa.blocks.defs#paragraph" as const;
+const headingType = "pub.oxa.blocks.defs#heading" as const;
+const codeType = "pub.oxa.blocks.defs#code" as const;
+const thematicBreakType = "pub.oxa.blocks.defs#thematicBreak" as const;
 
 const encoder = new TextEncoder();
 
@@ -421,7 +421,7 @@ export function oxaToAtproto(
   options: OxaToAtprotoOptions = {},
 ): AtprotoDocument {
   return {
-    $type: "pub.oxa.document.document",
+    $type: "pub.oxa.document",
     ...getOptionalDocumentFields(session, document),
     children: mapKnownBlocks(session, document.children),
     createdAt: options.createdAt ?? new Date().toISOString(),

packages/oxa/src/cli.test.ts

@@ -77,15 +77,15 @@ describe("oxa cli", () => {
   describe("convert", () => {
     const createdAt = "2026-03-22T00:00:00.000Z";
     const expectedConverted = {
-      $type: "pub.oxa.document.document",
+      $type: "pub.oxa.document",
       title: {
         text: "CLI Example",
         facets: [],
       },
       metadata: { license: "CC-BY-4.0" },
       children: [
         {
-          $type: "pub.oxa.document.defs#paragraph",
+          $type: "pub.oxa.blocks.defs#paragraph",
           text: "Hello from CLI",
           facets: [],
         },