Site Json Announcement

site.json — Site Resource Declaration


site.json is a machine-readable declaration of a website and the public resources it makes available.

It provides software, crawlers, indexing systems, AI systems, research tools, and other automated consumers with a structured description of a site's public content.

Chaos MVC can generate this resource automatically from the site's existing public resources and validate the completed declaration against the STN-LABZ Site Resource Schema before publication.

The standard location is:

/site.json


For example:

https://example.com/site.json


The governing schema is:

https://schema.stn-labz.com/site/v1/schema.json


Current schema version:

1.0



Purpose


Traditional discovery mechanisms describe different portions of a website.

A sitemap primarily identifies URLs. RSS describes feed content. llms.txt can provide a human-readable map for language-model-oriented consumers.

site.json serves a different purpose.

It provides a structured declaration of:

  • the website itself;
  • public resources available from the website;
  • the type of each resource;
  • titles and descriptions;
  • resource language;
  • whether the resource is intended for indexing;
  • publication and modification dates when available;
  • relationships between resources when declared.

The result is a predictable JSON document that software can consume without having to infer the basic structure of the site from HTML.


The STN-LABZ Site Resource Schema


A valid site.json document follows the STN-LABZ Site Resource Schema.

The document identifies its schema directly:

{
  "$schema": "https://schema.stn-labz.com/site/v1/schema.json",
  "version": "1.0"
}


The schema is the authority for the structure of the document.

Chaos MVC does not maintain a separate local copy of the schema for validation.

During generation, Chaos MVC retrieves the authoritative schema from:

https://schema.stn-labz.com/site/v1/schema.json


The generated declaration must validate against that remote schema before it can be published.


Document Structure


A site.json document contains four required top-level properties:

{
  "$schema": "https://schema.stn-labz.com/site/v1/schema.json",
  "version": "1.0",
  "site": {},
  "resources": []
}


These properties identify:

  • the governing schema;
  • the schema version;
  • the website;
  • the website's declared public resources.

Additional top-level properties are not permitted by version 1.0 of the schema.


Site Declaration


The site object describes the website itself.

It requires:

  • url
  • name
  • description
  • language

Example:

{
  "site": {
    "url": "https://example.com",
    "name": "Example Site",
    "description": "An example website.",
    "language": "en"
  }
}


url


The canonical URL of the website.

It must be a valid URI.

name


The name of the website.

It must contain at least one character.

description


A description of the website.

It must contain at least one character.

language


The language used by the website.

For example:

en



Resources


The resources array contains declarations for public resources provided by the website.

A resource requires:

  • url
  • type
  • title
  • description
  • language
  • index

Example:

{
  "url": "https://example.com/about",
  "type": "page",
  "title": "About",
  "description": "Information about the organization.",
  "language": "en",
  "index": true
}


Resources may additionally contain:

  • published
  • modified
  • relationships


Resource Types


Version 1.0 recognizes the following resource types:

page
article
documentation
software
product
download
image
feed
person
organization
event
other


The resource type gives consumers a basic semantic description of what the URL represents.

page


A general public webpage.

article


An article, post, announcement, or similar published content when the producer identifies it as such.

documentation


Technical, project, API, software, or other documentation.

software


A software resource.

product


A product or product information resource.

download


A downloadable resource.

image


An image resource.

feed


A machine-readable content feed such as RSS.

person


A resource representing a person.

organization


A resource representing an organization.

event


A resource representing an event.

other


A public resource whose semantics are not known or do not fit one of the defined types.

other is important for deterministic generation.

A generator should not guess the semantic meaning of a resource merely from its URL, module name, or content. When an authoritative type is unavailable, other provides an explicit representation without inventing information.


Indexing Declaration


Every resource contains an index boolean.

For example:

{
  "index": true
}


or:

{
  "index": false
}


This provides an explicit machine-readable declaration of whether the resource is intended for indexing.

In the current Chaos MVC generator, resources discovered through its public-resource authorities are emitted with:

{
  "index": true
}


because the generator is describing resources already determined to be public.


Publication and Modification Dates


Resources may contain publication and modification dates.

Example:

{
  "published": "2026-09-15",
  "modified": "2026-09-15"
}


Dates use the JSON Schema date format:

YYYY-MM-DD


Chaos MVC normalizes available creation and update timestamps to this format before including them.

If an authoritative date is unavailable, the optional field does not need to be invented.


Relationships


A resource may contain a relationships object.

Supported relationships are:

  • author
  • publisher
  • documentation
  • download
  • parent
  • related

Example:

{
  "relationships": {
    "author": "https://example.com/people/example-author",
    "publisher": "https://example.com",
    "documentation": "https://example.com/docs",
    "download": "https://example.com/download",
    "parent": "https://example.com/project",
    "related": [
      "https://example.com/resource-a",
      "https://example.com/resource-b"
    ]
  }
}


Relationship values are URIs.

The related property is an array of unique URIs.

Relationships are optional. They should be declared when the relationship is known rather than inferred without authority.


Chaos MVC Implementation


Chaos MVC integrates site.json into its existing site discovery system.

The generator derives the declaration from existing authoritative sources instead of introducing a separate resource registry.

The current discovery sources include:

  • public Chaos MVC Core routes;
  • public user modules;
  • published Pages;
  • published Posts;
  • the public RSS feed.

This follows the same general discovery architecture used by Chaos MVC for its other generated discovery resources.


Core Routes


Public Core controller roots can be represented as resources of type:

page


Internal Core controllers are explicitly excluded from publication.

This prevents implementation controllers and administrative infrastructure from becoming advertised public resources simply because controller files exist.

Examples of internal Core functionality include administrative, authentication, generator, health, theme, and infrastructure controllers.

Discovery therefore distinguishes between:

Controller exists


and:

Controller represents a public resource


Those are not assumed to mean the same thing.


User Modules


Chaos MVC discovers user modules from:

/user/modules/{slug}/


Module discovery is inert.

The discovery process examines the filesystem and module declaration without executing module PHP code.

A discoverable module must satisfy the module discovery requirements, including:

  • a valid module slug;
  • a real module directory rather than a symbolic-link directory;
  • a valid module.json;
  • matching module identity;
  • an appropriate controller file;
  • an index route declared by the module.

A module without sufficient authoritative semantic information is emitted as:

other


rather than having a resource type guessed from its name.


Pages


Chaos MVC Pages are discovered from:

/user/pages/{slug}/


with metadata provided by:

page.json


Only valid, published Pages are included.

Pages are represented as:

page


A Page such as:

/user/pages/about/


is represented by its public URL:

https://example.com/about


The internal filesystem location is not exposed as the public resource URL.


Posts


Published Posts are discovered through the existing Posts public-feed authority.

Individual published Posts are represented as:

article


When authoritative timestamps are available, Chaos MVC can include normalized published and modified dates.

Unpublished content is not included as a public resource.


RSS


The generated RSS resource is represented as:

feed


For a standard Chaos MVC installation this may appear as:

https://example.com/rss.xml



Deterministic Generation


The Chaos MVC implementation is designed around deterministic discovery.

The same authoritative site state should produce the same resource declaration.

The generator does not attempt to make speculative judgments about resources.

Its general process is:

Discover
    ↓
Normalize
    ↓
Deduplicate
    ↓
Sort
    ↓
Generate
    ↓
Validate
    ↓
Publish


Resources are deduplicated by URL and sorted deterministically.

Known information is represented as known information.

Unknown information is not silently converted into assumed information.

This follows a central Chaos MVC engineering principle:

Determinism ≠ Probably.


Remote Schema Validation


Generation alone is not sufficient for publication.

Before a new site.json replaces the current public declaration, Chaos MVC retrieves:

https://schema.stn-labz.com/site/v1/schema.json


The retrieved schema must itself satisfy the expected authority checks.

The schema $id must identify the expected STN-LABZ schema:

https://schema.stn-labz.com/site/v1/schema.json


Chaos MVC then validates the generated candidate against the retrieved schema.

The validation process supports the schema features required by Site Resource Schema v1, including:

  • $ref
  • const
  • enum
  • type
  • required
  • properties
  • additionalProperties
  • items
  • uniqueItems
  • minLength
  • URI format validation
  • date format validation

Only a candidate that passes validation proceeds to publication.


Fail-Closed Publication


site.json uses fail-closed publication.

If the remote schema cannot be retrieved, the candidate is not published.

If the remote schema is malformed, the candidate is not published.

If the retrieved schema does not identify itself as the expected authoritative schema, the candidate is not published.

If the generated document fails schema validation, the candidate is not published.

The existing known-good public declaration remains in place.

Conceptually:

Generate candidate
        ↓
Fetch authoritative schema
        ↓
Verify schema authority
        ↓
Validate candidate
        ↓
      PASS?
      /   \
    Yes    No
     |      |
 Publish   Reject
     |      |
New file   Existing file remains


This prevents an invalid generation attempt from replacing a previously valid public resource.


Atomic Publication


Chaos MVC generates and validates the candidate before replacing the public file.

The target is:

/public/site.json


Temporary publication state is kept separate from the current public resource.

The existing target is preserved during replacement so that a publication failure can be recovered without intentionally replacing the known-good declaration with an invalid candidate.

Validation therefore occurs before the generated declaration becomes authoritative public output.


Admin Integration


site.json is integrated into the Chaos MVC Admin index refresh process.

The site discovery refresh now generates:

sitemap.xml
ror.xml
llms.txt
rss.xml
site.json


The Admin refresh process invokes the appropriate generator for each resource.

For site.json, successful generation includes successful remote schema validation.

A failure in generation or validation is reported rather than silently treated as a successful refresh.


Discovery From HTML


A website may advertise its Site Resource Declaration from its HTML <head>.

Example:

<!-- Site Resource Declaration -->
<link
    rel="alternate"
    type="application/json"
    title="Site Resource Declaration"
    href="https://example.com/site.json"
/>


This gives consumers examining the site's HTML an explicit path to the machine-readable declaration.

The declaration also remains directly accessible at:

/site.json



Relationship to Other Discovery Resources


site.json does not replace the existing discovery mechanisms used by Chaos MVC.

It complements them.

A Chaos MVC site may publish:

/sitemap.xml
/ror.xml
/llms.txt
/rss.xml
/site.json


Each serves a different role.

sitemap.xml


Provides established search-engine-oriented URL discovery.

ror.xml


Provides ROR-compatible resource discovery.

llms.txt


Provides a text-oriented map of public site resources.

rss.xml


Provides a feed of published content.

site.json


Provides a schema-defined JSON declaration of the website and its public resources.

Together they allow different consumers to discover the site using formats appropriate to their purpose.


Example


A simplified site.json might look like this:

{
  "$schema": "https://schema.stn-labz.com/site/v1/schema.json",
  "version": "1.0",
  "site": {
    "url": "https://example.com",
    "name": "Example Site",
    "description": "An example Chaos MVC website.",
    "language": "en"
  },
  "resources": [
    {
      "url": "https://example.com/about",
      "type": "page",
      "title": "About",
      "description": "Information about Example Site.",
      "language": "en",
      "index": true
    },
    {
      "url": "https://example.com/posts/example-post",
      "type": "article",
      "title": "Example Post",
      "description": "An example published article.",
      "language": "en",
      "index": true,
      "published": "2026-09-15",
      "modified": "2026-09-15"
    },
    {
      "url": "https://example.com/rss.xml",
      "type": "feed",
      "title": "RSS Feed",
      "description": "Published content feed.",
      "language": "en",
      "index": true
    }
  ]
}



Design Principles


The Site Resource Declaration is built around several simple principles.

Machine Readable


The declaration uses JSON so automated consumers can parse the document directly.

Schema Defined


The structure is governed by a published JSON Schema rather than undocumented conventions.

Explicit


Resource properties are declared rather than requiring consumers to infer basic site semantics.

Deterministic


Generators should derive output from authoritative inputs using stable rules.

Non-Speculative


Unknown semantics should remain unknown rather than being guessed.

Fail Closed


An invalid candidate must not replace a known-good declaration.

Extensible Through Versioning


The schema identifies its version explicitly:

{
  "version": "1.0"
}


Future changes can therefore be introduced through defined schema versions rather than silently changing the meaning of an existing format.


Current Chaos MVC Support


Chaos MVC currently supports generation of Site Resource Schema version:

1.0


using:

https://schema.stn-labz.com/site/v1/schema.json


The generated declaration is published at:

/public/site.json


and publicly available as:

/site.json


The implementation has been functionally tested with a generated declaration containing public Core resources, user modules, Pages, Posts, and RSS resources.


Summary


site.json gives a website a structured way to say:

This is the site, and these are the public resources it provides.

For Chaos MVC, the declaration is not maintained manually as another independent index.

It is derived from the site's existing authorities.

The process is:

Discover → Generate → Validate → Publish


The STN-LABZ Site Resource Schema defines what a valid declaration is.

Chaos MVC determines what public resources actually exist.

Remote schema validation determines whether the resulting declaration is structurally valid.

Only then does the generated site.json become public.