Inject title, description about features and properties from dataset specific JSON Schema (or other) file to be published on collections/(collection)/schema resource

[teezip]

Phases:

1. add specification to this issue how metadata is encoded (JSON Schema or other) / 2025-12
2. implementation planning as soon as there is test data with such metadata / 2026-01
3. implementation to Hakunapi and testing on nlsfi internal development service / 2026-01 .. 2026-02
4. published on Hakunapi 1.7.0 release

This is separate from #47 but related (also yaml configuration suggested how title, description etc would be configured).

Specification

JSON Schema files describing GeoPackage datasets provided by NLS of Finland are planned to be embedded on GPGK metadata tables and also delivered as separate files (along GPGK snapshot and changeset files and in future from some web persistent URI service too).

Hakunapi service configuration would be feeded also by such JSON Schema file that would be used by Hakunapi as additional configuration regarding features and feature properties. The goal is that titles / descriptions would not be copied to Hakunapi standard configuration files but read from JSON Schema file.

Hakunapi would then use such descriptive information on collections/{collection}/schema resources returning JSON Schema on feature and feature property elements.

Sample JSON Schema file (not a real data model, but should shows what is planned):

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "http://paikkatiedot.fi/def/1000007/topodb/open-data_v1.0.1",
    "title": "Topographic data",
    "description": "Description about Topographic Database and data it provides. And what dataset version represented here....",
    "x-crs": "http://www.opengis.net/def/crs/EPSG/0/10774",
    "properties": {
        "building_part_area": {
            "type": "object",
            "title": "Building part (area)",
            "description": "Description about this feature type ...",
            "properties": {
                "map_data_id": {
                    "type": "string",
                    "title": "Map data id",
                    "description": "Unique identifier for the feature"
                },
                "building_function_id": {
                    "type": "string",
                    "title": "Function",
                    "description": "Description about this codelist.....",
                    "enum": ["001", "002", "003", "004"],
                    "x-codelist-uri": "http://uri.suomi.fi/codelist/nlsfi-topodb/building_function_id",                   
                },
                "geom" : {
                    "type": "object",
                    "x-geometry-type": "POLYGON Z",
                    "title": "Geometry field....",
                    "description": "Description about this geometry field.....",
                },
            }
        }
    }
}

Some notes about example JSON Schema metadata / configuration below.

At top level:

• $id: identifies dataset application schema and it's specific version
• title / description: descriptive text about a dataset
• x-crs: crs used in dataset export files (GPGK snapshot and changesets), do not define the crs in Hakunapi datasource (like PostGIS storage crs), but chances are that these are the same
• no place to inject this information at least on collections/{collection}/schema

At feature level (like building_part_area):

• title / description: descriptive text about a feature
• injected on a feature type in collections/{collection}/schema

At feature property level, all properties (like map_data_id):

• title / description: descriptive text about a feature property
• injected on a feature property in collections/{collection}/schema

For an enumerated property (like building_function_id) also:

• enum: allowed values for this enumerated property (for convenience - reader of a schema file do not have to always fetch this from a separate codelist registry service)
• x-codelist-uri: persistent URI for a codelist (could be a forwarding service that forwards to a codelist registry like https://koodistot.suomi.fi/)

For a geometry property (like geom this refers to a field in GPGK file the JSON Schema file is describing) also:

• x-geometry-type: an identifier that are defined by WKT, that is "POINT", "POINT Z", "POLYGON", "POLYGON Z", etc. (if geometry is 2D then without postfix, if geometry is 3D then with "Z" postfix)

The JSON Schema in a file described above is an application schema of GPGK dataset. On the other hand Hakunapi on collections/{collection}/schema resource publishes a JSON Schema representing GeoJSON features provided by an OGC API Features service. There is surely differences between these two JSON schemas. For example geometry types on collections/{collection}/schema should be announced as it's defined by OGC API Features Part 5 and related standards, not using the custom definition defined by x-geometry-type.