Add schema.oaedata.org docs site (#18)

* update prefix for oae data protocol schema

* further doc updates

* update home page

* docs: curated nav, explainer pages, CNAME, schema ID update

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* add JSON-LD context generation and docs

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: getting started, contributing, metadata builder pages, screenshots

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* move context.jsonld copy to gendoc step

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* site title: OAE Data Protocol - Schema

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* update schema doc pages

* update excel language

* update root schema file to serve at schema.oaedata.org/OAEDataSchema

* add styling, update variable diagram

* clean up intro text, update logo

* update readme

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: clevinson

Makefile

@@ -125,7 +125,7 @@ gen-examples:
 
 # generates all project files
 
-gen-schemas: gen-project gen-validation-schema
+gen-schemas: gen-project gen-validation-schema gen-context
 
 gen-project: $(PYMODEL)
 	$(RUN) gen-project ${CONFIG_YAML} -d $(DEST) $(SOURCE_SCHEMA_PATH)
@@ -147,6 +147,10 @@ ifneq ($(strip ${GEN_TS_ARGS}),)
 	$(RUN) gen-typescript ${GEN_TS_ARGS} $(SOURCE_SCHEMA_PATH) >${DEST}/typescript/${SCHEMA_NAME}.ts
 endif
 
+gen-context:
+	$(RUN) gen-jsonld-context $(SOURCE_SCHEMA_PATH) > $(DEST)/jsonld/context.jsonld
+	@echo "✓ Generated JSON-LD context"
+
 gen-validation-schema:
 	$(RUN) python -c "from linkml.generators.jsonschemagen import JsonSchemaGenerator; \
 		gen = JsonSchemaGenerator( \
@@ -219,8 +223,17 @@ $(DOCDIR):
 	mkdir -p $@
 
 gendoc: $(DOCDIR)
-	cp -rf $(SRC)/docs/files/* $(DOCDIR) ; \
 	$(RUN) gen-doc ${GEN_DOC_ARGS} -d $(DOCDIR) $(SOURCE_SCHEMA_PATH)
+	mv $(DOCDIR)/index.md $(DOCDIR)/OAEDataSchema.md
+	cp -rf $(SRC)/docs/files/* $(DOCDIR)
+	cp $(DEST)/jsonld/context.jsonld $(DOCDIR)/context.jsonld
+	@# Create section directories with index pages for navigation.indexes
+	mkdir -p $(DOCDIR)/getting-started $(DOCDIR)/projects-experiments $(DOCDIR)/datasets $(DOCDIR)/variables $(DOCDIR)/instruments-calibration
+	mv $(DOCDIR)/getting-started.md $(DOCDIR)/getting-started/index.md
+	mv $(DOCDIR)/projects-experiments.md $(DOCDIR)/projects-experiments/index.md
+	mv $(DOCDIR)/datasets.md $(DOCDIR)/datasets/index.md
+	mv $(DOCDIR)/variables.md $(DOCDIR)/variables/index.md
+	mv $(DOCDIR)/instruments-calibration.md $(DOCDIR)/instruments-calibration/index.md
 
 testdoc: gendoc serve
 

README.md

@@ -11,22 +11,23 @@ for producing consistent data and metadata for Ocean Alkalinity Enhancement (OAE
 
 This repository provides machine-readable schemas and data standards for the protocol. It focuses on formal specifications for metadata about OAE projects, experiments, datasets, and individual data variables within datasets themselves (including instrumet, analysis, and calibration metadata).
 
-**For Protocol Compliance**: As of the v1.0 protocol launch (August 25, 2025), projects seeking to comply with the protocol guidelines should use the Excel templates available on the [protocol website](http://carbontosea.org/oae-data-protocol/1-0-0/). These templates are also available in the [`templates/excel`](./templates/excel) directory of this repository.
+**Creating Metadata**: The easiest way to produce a valid metadata file is the [OAE Metadata Builder](https://metadata.oaedata.org) — a web app that walks you through each section and exports a JSON file validated against these schemas. Excel templates from the [v1.0 protocol launch](http://carbontosea.org/oae-data-protocol/1-0-0/) (August 25, 2025) remain available in [`templates/excel`](./templates/excel) and on the protocol website.
 
-**Beta Testing**: Organizations and researchers interested in testing the software tooling under development in this repository should contact [data@carbontosea.org](mailto:data@carbontosea.org).
+**Beta Testing**: Organizations and researchers interested in testing the software tooling under development should contact [data@carbontosea.org](mailto:data@carbontosea.org).
 
 ## What's Inside
 
 This repository contains [LinkML](https://linkml.io) schema definitions that can generate:
 
 - **JSON Schema** for data validation and form generation
 - **Python dataclasses** for programmatic data handling
+- **JSON-LD context** for linked-data interoperability
 - **Documentation** (what you're reading now!)
 - Support for multiple serialization formats (JSON, YAML, RDF, etc.)
 
 ## Documentation
 
-📖 **[View the schema documentation](https://submarine-mrv.github.io/oae-data-protocol)**
+📖 **[schema.oaedata.org](https://schema.oaedata.org)**
 
 ## Quick Start
 
@@ -36,7 +37,8 @@ This repository contains [LinkML](https://linkml.io) schema definitions that can
 
 The generated schemas are available in the `project/` directory:
 
-- `project/jsonschema/` - JSON Schema definitions
+- `project/jsonschema/` - JSON Schema definitions (including `*.validation.schema.json` for runtime validation)
+- `project/jsonld/context.jsonld` - JSON-LD context
 - `src/oae_data_protocol/datamodel/` - Python dataclasses
 
 ## Repository Structure
@@ -72,7 +74,8 @@ make gen-project
 
 ```bash
 make help              # Show all available commands
-make gen-project       # Regenerate schemas and Python code
+make gen-schemas       # Regenerate Python, JSON Schema, validation schema, and JSON-LD context
+make gen-project       # Regenerate Python dataclasses and base JSON Schema only
 make test             # Run tests
 make lint             # Lint LinkML schemas
 make serve            # Build and serve documentation locally

mkdocs.yml

@@ -1,34 +1,76 @@
 ---
-site_name: "oae-data-protocol"
+site_name: "OAE Data Protocol: Schema Documentation"
+site_url: https://schema.oaedata.org
+repo_url: https://github.com/submarine-mrv/oae-data-protocol
+
 theme:
   name: material
-  # palette:
-  #  scheme: slate
-  #  primary: cyan
+  favicon: img/favicon.ico
+  logo: img/cts-logo.png
   features:
+    - navigation.indexes
     - content.tabs.link
+
 plugins:
   - search
-  - mermaid2
-  - mknotebooks:
-      execute: false
   - mermaid2:
       version: 10.9.0
-nav:
-  # - Home: home.md
-  - Index: index.md
-  - About: about.md
-site_url: https://clevinson.github.io/oae-data-protocol
-repo_url: https://github.com/clevinson/oae-data-protocol
+
 markdown_extensions:
   - tables
+  - admonition
+  - pymdownx.details
+  - attr_list
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:mermaid2.fence_mermaid_custom
+
+nav:
+  - Home: index.md
+  - Getting Started:
+    - getting-started/index.md
+    - Metadata File Format: metadata-format.md
+    - Metadata Builder: metadata-builder.md
+    - Contributing: contributing.md
+  - Projects & Experiments:
+    - projects-experiments/index.md
+    - Project: Project.md
+    - Experiment: Experiment.md
+    - InSituExperiment: InSituExperiment.md
+    - Intervention: Intervention.md
+    - Tracer: Tracer.md
+    - InterventionWithTracer: InterventionWithTracer.md
+    - Model: model.md
+  - Datasets:
+    - datasets/index.md
+    - FieldDataset: FieldDataset.md
+    - ModelOutputDataset: ModelOutputDataset.md
+  - Variables:
+    - variables/index.md
+    - InSituVariable: InSituVariable.md
+    - MeasuredVariable: MeasuredVariable.md
+    - CalculatedVariable: CalculatedVariable.md
+    - NonMeasuredVariable: NonMeasuredVariable.md
+    - DiscretePHVariable: DiscretePHVariable.md
+    - DiscreteTAVariable: DiscreteTAVariable.md
+    - DiscreteDICVariable: DiscreteDICVariable.md
+    - DiscreteCO2Variable: DiscreteCO2Variable.md
+    - HPLCVariable: HPLCVariable.md
+  - Instruments & Calibration:
+    - instruments-calibration/index.md
+    - AnalyzingInstrument: AnalyzingInstrument.md
+    - PHInstrument: PHInstrument.md
+    - CRMInstrument: CRMInstrument.md
+    - CO2GasDetector: CO2GasDetector.md
+    - Calibration: Calibration.md
+  - Controlled Vocabularies: vocabularies.md
+  - Full Schema Index: OAEDataSchema.md
+
+extra_css:
+  - stylesheets/extra.css
+
 extra_javascript:
   - https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js
   - javascripts/tablesort.js
-
-# Uncomment this block to enable use of Google Analytics.
-# Replace the property value with your own ID.
-# extra:
-#   analytics:
-#     provider: google
-#     property: G-XXXXXXXXXX