Skip to content

[WIP] New reference documentation #222

Draft
jenningsanderson wants to merge 3 commits intomainfrom
injectable-schema-refs
Draft

[WIP] New reference documentation #222
jenningsanderson wants to merge 3 commits intomainfrom
injectable-schema-refs

Conversation

@jenningsanderson
Copy link
Collaborator

@jenningsanderson jenningsanderson commented Aug 13, 2025

Moving to Pydantic!

This PR updates and simplifies the docs to show easier, table-based schema docs.

Enhancements to docs code:

  1. Removes Docusaurus JSON Schema Plugin.
  2. Enables (significantly) faster builds.
  3. Reduction in serving of raw YAML files.

/schema/reference Updates:

Today, everything available under docs.overturemaps.org/schema lives here: https://github.com/OvertureMaps/schema/tree/dev/docs/schema. When docusaurus builds the docs, it fetches the .mdx, schema, and examples from the schema repo. This is a lot of moving parts and kind of ugly.

This PR removes that requirement in favor of simple, machine-readable markdown files that can be self-generated by the schema and used by documentation.

See https://staging.overturemaps.org/docs/pr/222/schema/reference/address/ for an example of how we envision these reference docs rendering.

Next Steps:

Before this is ready to merge, we need to develop the ability for the schema to create self-describing documentation with examples as markdown files, example:

# Place

A Place is a point representation of a real-world facility, service, or amenity.

Place features are compatible with GeoJSON Point features.

## Fields

| Name | Type | Description |
|-----:|:----:|-------------|
| `id` | `string` |  |
| `theme` | `"places"` |  |
| `type` | `"place"` |  |
| `geometry` | `geometry` | Position of the place |
| `names` | `object` (`[Names](../../Names/names)`) (optional) |  |
| `names.primary` | `string` | The most commonly used name. |
| `names.common` | `object` (optional) |  |
...

## Examples

| Column | Value |
|-------:|-------|
| `geometry` | `POINT (-151.7990018 -79.5664328)` |
| `categories.alternate` | `null` |
| `categories.primary` | `media_news_website` |
| `confidence` | `0.8015267175572519` |
| `websites` | `[https://www.primenewsmonde.bj/]` |

The full schema should be a series of markdown files nested by theme/type that have relative links. We can adjust the SmartTable component as necessary to make the links work — but the markdown should be a nice, standalone set of files.

If the examples that were embedded were actually derived from the examples in the schema repository after being validated by the schema itself, that would be best case scenario.

Once this ability exists, we can update this repository to fetch these markdown files (or checkout schema and build the markdown as part of the publish). The idea is these files can be dropped directly into docs/schema to power this part of the documentation.

Docs Preview

Example:
image

@jenningsanderson jenningsanderson force-pushed the injectable-schema-refs branch 3 times, most recently from b6bf09d to fa2e953 Compare August 16, 2025 00:09
@danabauer danabauer self-assigned this Sep 17, 2025
@jenningsanderson jenningsanderson added documentation Improvements or additions to documentation enhancement New feature or request labels Feb 7, 2026
@jenningsanderson jenningsanderson changed the base branch from main to gif-to-mp4-conversion February 9, 2026 19:49
@jenningsanderson jenningsanderson force-pushed the injectable-schema-refs branch 2 times, most recently from ad1679b to d936cb3 Compare February 9, 2026 19:59
@jenningsanderson jenningsanderson changed the base branch from gif-to-mp4-conversion to main February 9, 2026 20:19
This change restructures the docs build to remove the dependency on the schema repository, enabling faster builds and simpler deployment.

Key changes:
- Add injectable schema references for dynamic content
- Reorganize example files and schema definitions
- Optimize image assets (convert large GIFs to MP4s, compress PNGs)
- Add staging deployment workflow
- Update linting and formatting configurations
- Fix package-lock.json for cross-platform compatibility
Generated from overture-schema-codegen (code-generation branch)
using explicit theme selection to exclude internal types:

  overture-codegen generate \
    --theme addresses --theme base --theme buildings \
    --theme divisions --theme places --theme transportation \
    --format markdown --output-dir docs/schema/reference

Cross-theme types (names, perspectives, cartography, scoping,
strings, sources, primitives, geometry) now live under
types/{subsystem}/ instead of flat at reference root or under
Names/.

Transportation segments (road, rail, water) and their ~50
referenced types are not yet generated -- the codegen doesn't
decompose the Segment discriminated union into individual
models. A WIP banner on the schema index notes this gap.

Broken link warnings enabled in docusaurus.config.js to
surface pre-existing and new issues during builds.
The codegen now outputs a flatter directory structure: types/ split
into core/ (names, cartography, scoping, sources, perspectives) and
system/ (primitives, string types, ref types). Theme feature-type
subdirectories removed (e.g. addresses/address/address.md becomes
addresses/address.md). Internal cross-reference links updated to match;
no content changes.

sidebars.js rewritten to match the new layout.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants

Comments