📖 Initial documentation

Author: rowanc1

.gitignore

@@ -1,2 +1,4 @@
 node_modules
 dist
+docs/_build
+docs/schema

CONTRIBUTING.md

@@ -17,7 +17,7 @@ pnpm install
 
 The OXA schema is defined as individual YAML files in the `schema/` directory. YAML was chosen for schema definitions because it is more human-readable and easier to edit than JSON.
 
-The `schema/schema.json` file is **auto-generated** from the YAML sources and should not be edited directly. Any schema changes should be made to the `.yaml` files, then regenerated:
+The `schema/schema.json` file is **autogenerated** from the YAML sources and should not be edited directly. Any schema changes should be made to the `.yaml` files, then regenerated:
 
 ```bash
 pnpm codegen json
@@ -72,3 +72,7 @@ pnpm codegen docs      # Generate MyST documentation
 # Build all packages
 pnpm build
 ```
+
+## Documentation
+
+The documentation uses [MyST](https://mystmd.org) and requires the automated codegen tool to run. To start the documentation use `npm install -g mystmd` and run `myst start` in the `docs/` folder. The online documentation is hosted using Curvenote under https://oxa.dev

docs/index.md

@@ -0,0 +1,21 @@
+---
+title: OXA Schema
+---
+
+> **A foundation for interoperable, structured scientific content.**
+> OXA defines open, extensible JSON schemas that describe modular and composable scientific documents — bridging the gap between authoring systems like **Stencila**, **MyST**, **Quarto** and the scientific publishing ecosystem which uses tools like **JATS**.
+
+## Overview
+
+The **Open Exchange Architecture (OXA)** is a specification for representing scientific documents and their components as structured JSON objects.
+It’s designed to enable **exchange, interoperability, and long-term preservation** of scientific knowledge, while remaining compatible with modern web and data standards.
+
+OXA provides schemas and examples for representing:
+
+- Executable and interactive research components
+- Text, math, figures, code, and metadata
+- Authors, affiliations, and licenses
+- Hierarchical structures like sections and paragraphs
+- Inline formatting (strong, emphasis, quote, etc.)
+
+The format is inspired by **[unified.js](https://unifiedjs.com)** and **Pandoc AST**, following a **typed node model** with `children` arrays that form a tree.

docs/myst.yml

@@ -0,0 +1,20 @@
+# See docs at: https://mystmd.org/guide/frontmatter
+version: 1
+project:
+  id: oxa-docs
+  title: Open Exchange Architecture
+  description: A specification for representing scientific documents and their components as structured objects.
+  license: CC-BY-4.0
+  github: https://github.com/oxa-dev/oxa
+  abbreviations:
+    OXA: Open Exchange Architecture
+    AST: Abstract Syntax Tree
+    JATS: Journal Article Tag Suite
+    JSON: JavaScript Object Notation
+  toc:
+    - file: index.md
+    - title: Schema Reference
+      children:
+        - pattern: schema/*.md
+site:
+  template: book-theme

packages/oxa-types-ts/package.json

@@ -25,7 +25,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/oxa-dev/oxa.git",
+    "url": "git+https://github.com/oxa-dev/oxa.git",
     "directory": "packages/oxa-types-ts"
   }
 }

scripts/codegen.ts

@@ -8,6 +8,7 @@
 import { program } from "commander";
 import { generateJson } from "./lib/generate-json.js";
 import { generateTs } from "./lib/generate-ts.js";
+import { generateDocs } from "./lib/generate-docs.js";
 import { validateSchemas } from "./lib/validate.js";
 
 interface Generator {
@@ -19,6 +20,7 @@ interface Generator {
 const generators: Generator[] = [
   { name: "json", label: "JSON Schema", fn: generateJson },
   { name: "ts", label: "TypeScript types", fn: generateTs },
+  { name: "docs", label: "Schema documentation", fn: generateDocs },
 ];
 
 async function validate(): Promise<void> {

scripts/lib/generate-docs.ts

@@ -0,0 +1,189 @@
+/**
+ * Generate Markdown documentation files from the OXA JSON Schema.
+ *
+ * Creates individual documentation files for each schema type in the docs/schema/
+ * directory, formatted for use in documentation sites.
+ */
+
+import { mkdirSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+
+import { loadMergedSchema } from "./schema.js";
+
+const OUTPUT_DIR = join(import.meta.dirname, "../../docs/schema");
+
+interface SchemaProperty {
+  type?: string;
+  const?: string;
+  description?: string;
+  items?: { $ref?: string; type?: string };
+  $ref?: string;
+  minimum?: number;
+  maximum?: number;
+  additionalProperties?: boolean;
+}
+
+interface SchemaDefinition {
+  title: string;
+  description?: string;
+  type?: string;
+  anyOf?: Array<{ $ref: string }>;
+  properties?: Record<string, SchemaProperty>;
+  required?: string[];
+}
+
+export async function generateDocs(): Promise<void> {
+  // Delete and recreate output directory
+  try {
+    rmSync(OUTPUT_DIR, { recursive: true, force: true });
+  } catch (error) {
+    // Directory might not exist, which is fine
+  }
+  mkdirSync(OUTPUT_DIR, { recursive: true });
+
+  const schema = loadMergedSchema();
+  const definitions = schema.definitions as Record<string, SchemaDefinition>;
+
+  // Generate documentation for object types (non-union types)
+  for (const [name, def] of Object.entries(definitions)) {
+    if (!def.anyOf && def.type === "object") {
+      const content = generateDocContent(name, def);
+      const filePath = join(OUTPUT_DIR, `${name.toLowerCase()}.md`);
+      writeFileSync(filePath, content);
+      console.log(`Generated ${filePath}`);
+    }
+  }
+
+  // Generate documentation for union types
+  for (const [name, def] of Object.entries(definitions)) {
+    if (def.anyOf) {
+      const content = generateUnionDocContent(name, def);
+      const filePath = join(OUTPUT_DIR, `${name.toLowerCase()}.md`);
+      writeFileSync(filePath, content);
+      console.log(`Generated ${filePath}`);
+    }
+  }
+}
+
+function generateDocContent(name: string, def: SchemaDefinition): string {
+  const lines: string[] = [];
+
+  // Frontmatter
+  lines.push(`(oxa:${name.toLowerCase()})=`);
+  lines.push("");
+
+  // Heading
+  lines.push(`## ${name}`);
+  lines.push("");
+  lines.push("");
+
+  // Description
+  if (def.description) {
+    lines.push(def.description);
+    lines.push("");
+    lines.push("");
+  }
+
+  const required = new Set(def.required || []);
+
+  // Properties
+  for (const [propName, prop] of Object.entries(def.properties || {})) {
+    // Property header
+    if (prop.const) {
+      // Const types use italic _string_, with const value in parentheses
+      lines.push(`__${propName}__: _string_, ("${prop.const}")`);
+    } else if (prop.type === "array" && prop.items) {
+      const arrayType = getArrayItemType(prop.items);
+      lines.push(`__${propName}__: __array__ ("${arrayType}")`);
+    } else {
+      const propType = getPropertyType(prop);
+      lines.push(`__${propName}__: __${propType}__`);
+    }
+    lines.push("");
+
+    // Property description
+    if (prop.description) {
+      lines.push(`: ${prop.description}`);
+    }
+
+    // Reference hint for ref types (arrays with ref items get the hint)
+    if (prop.items?.$ref) {
+      const refName = prop.items.$ref.replace("#/definitions/", "");
+      lines.push(`: See @oxa:${refName.toLowerCase()}`);
+    }
+
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+function getPropertyType(prop: SchemaProperty): string {
+  if (prop.$ref) {
+    const refName = prop.$ref.replace("#/definitions/", "");
+    return refName;
+  }
+
+  switch (prop.type) {
+    case "string":
+      return "string";
+    case "integer":
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "array":
+      return "array";
+    case "object":
+      return "object";
+    default:
+      return "unknown";
+  }
+}
+
+function generateUnionDocContent(name: string, def: SchemaDefinition): string {
+  const lines: string[] = [];
+
+  // Frontmatter
+  lines.push(`(oxa:${name.toLowerCase()})=`);
+  lines.push("");
+
+  // Heading
+  lines.push(`## ${name}`);
+  lines.push("");
+  lines.push("");
+
+  // Description
+  if (def.description) {
+    lines.push(def.description);
+    lines.push("");
+    lines.push("");
+  }
+
+  // List union members
+  const members =
+    def.anyOf?.map((item) => {
+      const ref = item.$ref;
+      const typeName = ref?.replace("#/definitions/", "") || "unknown";
+      return typeName;
+    }) || [];
+
+  if (members.length > 0) {
+    lines.push(
+      `Union of: ${members.map((m) => `@oxa:${m.toLowerCase()}`).join(", ")}`,
+    );
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+function getArrayItemType(items: { $ref?: string; type?: string }): string {
+  if (items.$ref) {
+    return items.$ref.replace("#/definitions/", "");
+  }
+  if (items.type) {
+    return items.type;
+  }
+  return "unknown";
+}