CityJSON Extensions registry 📖

This is the official registry for CityJSON Extensions. It provides a centralised location where developers can discover, submit, and maintain CityJSON Extensions that extend the core CityJSON specification.

Overview

CityJSON Extensions allow you to add custom properties and objects to CityJSON datasets without modifying the core specification. This registry serves three key purposes:

• Discoverability: Software and developers can easily find and use existing Extensions
• Reliability: All Extensions are hosted in one location, eliminating CORS issues and broken links
• Learning: The community can learn from and build upon existing Extension implementations

Available Extensions

Extension	Description	Latest version	Schema	Developer(s)
energy-space-heating	CityJSON Energy Extension for Space Heating Demand Calculation	1.1.1	energy-space-heating.ext.json	Özge Tufan
lcc	Extension to model the topology of the city as a linear cell complex based on a combinatorial map.	0.3.0	lcc.ext.json	Stelios Vitalis
noise	Extension for Noise Emission Simulation	2.0.0	noise.ext.json	Hugo Ledoux
perception	To model the visual perception of buildings	0.6.0	perception.ext.json	Binyu Lei
quality	Application Domain Extension to data quality modeling	1.0.1	quality.ext.json	Grigory Ilizirov, Sagi Dalyot
shed	Example of an Extension for modelling sheds; meant as a template to learn how to construct an Extension	0.1.1	shed.ext.json	Hugo Ledoux

Using an Extension

To use a CityJSON Extension in your project:

1. Identify the Extension you need from the registry
2. Reference the Extension schema in your CityJSON file
3. Follow the Extension's documentation and examples

The URL to use is https://cityjson.github.io/extensions/{name}/{version}/{name}.ext.json. Example reference in a CityJSON file:

{
  "type": "CityJSON",
  "version": "2.0",
  "extensions": {
    "lamppost": {
      "url": "https://cityjson.github.io/extensions/lamppost/0.1.0/lamppost.ext.json",
      "version": "0.1.0"
    }
  }
}

Guidelines for submitting a new Extension

To create a new CityJSON Extension, refer to the CityJSON Extension page.

Before submitting to this registry, please ensure your Extension meets these criteria:

• Usefulness: The Extension should be useful to others and address a real need
• Novelty: Verify that no existing Extension already covers your use case
• Naming:
  • Must be unique across the registry
  • Lowercase only, no spaces or capitals
  • Use hyphens to separate multiple words (e.g., park-benches, solar-panels)
• Documentation: Include both the Extension schema file and at least one example file demonstrating its usage
• Licensing: Add a license file to your package so others can use your work. We recommend MIT or Apache 2.0. Not sure which? See choosealicense.com
• Quality: Code should be clear, well-documented, and follow best practices

Directory Structure

Each Extension follows this structure within the registry:

extensions/
├── shed/
│   └── 0.1.0/
│       └── ...
│   └── 0.1.1/
│       ├── examples/
│       │   └── shed_example.json
│       ├── README.md
│       ├── shed.ext.json          <-- (Extension schema)
│       ├── extension.toml         <-- (metadata)
│       └── LICENSE.txt
├── energy/
│   └── 1.0.0/
│       ├── examples/
│       ├── README.md
│       ├── energy.ext.json
│       ├── extension.toml
│       └── LICENSE.txt
└── ...

Required files for each version

File	Description
{name}.ext.json	The CityJSON Extension schema file containing the core definition
extension.toml	Metadata about the Extension (name, version, author, etc.)
README.md	Documentation explaining the Extension, its use cases, and examples (there is no template)
examples/ (folder)	Directory containing example CityJSON files using this Extension
LICENSE.txt	License file (MIT, Apache 2.0, or other)

Steps to submit an Extension

Once your Extension meets all the submission requirements above, follow these steps:

1. Fork the repository on GitHub

2. Create the Extension directory structure:

   git clone your-fork
   cd extensions
   mkdir -p extensions/{name}/{version}
   

3. Add the required files::

   • {name}.ext.json
   • extension.toml
   • README.md
   • examples/
   • LICENSE.txt

4. Ensure the correct URL format: Your Extension will be accessible at:

   https://cityjson.github.io/extensions/{name}/{version}/{name}.ext.json
   

5. Commit and push your changes to your fork

6. Create a pull request to the main repository with a clear description of your Extension

Extension schema template

Here's a minimal example for a (hypothetical) Lamppost Extension:

{
  "type": "CityJSONExtension",
  "name": "Lamppost",
  "uri": "https://cityjson.github.io/extensions/lamppost/0.1.0/lamppost.ext.json",
  "version": "0.1.0",
  "versionCityJSON": "2.0",
  "description": "Extension to model Lampposts and street lighting infrastructure.",
  "extraRootProperties": {},
  "extraAttributes": {},
  "extraSemanticSurfaces": {},
  "extraCityObjects": {
    "Lamppost": {
      "description": "A single lamppost object",
      "properties": {...}
    }
  }
}

Maintenance & Updates

• Versioning: Extensions follow Semantic Versioning (MAJOR.MINOR.PATCH)
• Backward Compatibility: Try to maintain backward compatibility when updating Extensions
• Version Updates: Submit new versions as separate directories (e.g., lamppost/0.2.0/)
• Deprecation: If an Extension is deprecated, clearly mark it in the README and documentation

Resources

• CityJSON Official Website
• CityJSON Specification
• CityJSON Extensions page
• Semantic Versioning
• Choose a License

Community

We welcome contributions from the community! If you have questions or suggestions:

• Open an issue: For bugs, questions, or feature requests
• Start a discussion: For broader topics or design questions
• Submit a pull request: To add a new Extension or improve existing ones

License

The registry itself is maintained by the CityJSON community. Each Extension in the registry is licensed according to its own LICENSE file.