fiboa · m-mohr · Aug 25, 2025 · Aug 30, 2024 · Feb 4, 2025 · Mar 9, 2025
diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
@@ -3,7 +3,7 @@ on:
   - push
   - pull_request
 jobs:
-  deploy:
+  docs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/setup-python@v5
@@ -15,7 +15,30 @@ jobs:
           pip install pipenv
           pipenv install
       - run: pipenv run test-docs
+  schema:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '>=3.9'
+      - uses: actions/checkout@v4
+      - name: Install pipenv
+        run: |
+          pip install pipenv
+          pipenv install
       - run: pipenv run test-schema
+  examples:
+    runs-on: ubuntu-latest
+    needs: schema
+    steps:
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '>=3.9'
+      - uses: actions/checkout@v4
+      - name: Install pipenv
+        run: |
+          pip install pipenv
+          pipenv install
       - run: pipenv run test-geojson-features
       - run: pipenv run test-geojson-collection
-      - run: pipenv run test-geoparquet
+      - run: pipenv run test-geoparquet
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,27 +11,34 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 - Property `category`
 - Property `determination_details`
+- Information about the encoding of datatypes at the collection-level
 
 ### Changed
 
-- ...
-
-### Deprecated
-
-- ...
+- Switched from v0.1.0 to v0.2.0 of the schema language
+- Renamed `fiboa_extensions` to `schemas`
+- Schemas must be valid HTTP(S) URLs
+- GeoParquet: Renamed Parquet metadata key from `fiboa` to `collection`
+- GeoJSON: Switched `contentEncoding` for data type `binary` from `binary` to `base64`
+- GeoJSON data types: `null` is not allowed any longer, instead omit the property
+- GeoJSON FeatureCollection: Collection-level data is provided at the top-level, not in a `fiboa` property
 
 ### Removed
 
-- Value `administrative` was removed from `determination_method` in favour of the new property `category`
+- Value `administrative` was removed from `determination_method` in favor of the new property `category`
+- `fiboa_version` in favor of adding the schema URL of the specification to `schemas`.
+- GeoJSON Feature: `links` property
 
 ### Fixed
 
 - Various minor clarifications and editorial enhancements
-- GeoParquet encoding: Properties that are optional can be omitted if all values are null values
-- GeoJSON encoding: Clarify the encoding of the top-level properties (including `links` and `fiboa`)
-- GeoJSON encoding: Clarify the use of RFC 7946
-- GeoParquet encoding for bounding boxes and objects
 - Added descriptions to the allowed values for `determination_method`
+- Clarified handling of missing values
+- GeoJSON: Clarify the encoding of the top-level properties (including `links` and `fiboa`)
+- GeoJSON: Clarify the use of RFC 7946
+- GeoParquet: Properties that are optional can be omitted if all values are null values
+- GeoParquet: Added encoding for bounding boxes and objects
+- GeoParquet: Clarified the use of Map and Struct data types
 
 ## [v0.2.0] - 2024-04-10
 

diff --git a/CITATION.cff b/CITATION.cff
@@ -8,7 +8,7 @@ preferred-citation:
   type: standard
   title: "Field Boundaries for Agriculture (fiboa) specification"
   abstract: "Making field boundaries openly available in a unified way."
-  version: 0.2.0
+  version: 0.3.0
   year: 2024
   date-released: 2024-04-10
   license: Apache-2.0

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -40,6 +40,9 @@ We use pipenv to execute the tests.
 Start with the following command in the folder where this README is located:
 `pip install pipenv --user`
 
+Install the dependencies for the test:
+`pipenv install`
+
 Finally, you can run the tests as follows:
 
 - To check the markdown run: `pipenv run test-docs`

diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@ This repository contains the core specification for fiboa, including the data sc
 For more context, information on the ecosystem, and points of contact see the
 [fiboa github organization](https://github.com/fiboa/).
 
-- Version: **0.2.0**
+- Version: **0.3.0**
 
 > [!IMPORTANT]  
 > The fiboa specification is a work in progress.
@@ -29,15 +29,30 @@ The specification in this repository consists of three parts:
 - [GeoJSON Encoding](geojson/README.md)
 - [GeoParquet Encoding](geoparquet/README.md)
 
-To completent the specification, there are also best practices and extensions available:
+To complement the specification, there are also best practices and extensions available:
 
 - [Best Practices](best-practices/README.md)
 - [Extensions](https://github.com/fiboa/extensions/)
 
-The repository also contains additional information about the project:
+## Relation to other standards and working groups
 
-- [Changelog](CHANGELOG.md)
-- [Citation Details (as CFF file)](CITATION.cff)
+fiboa doesn't aim to reinvent the wheel.
+Our aim is to align with existing efforts as much as possible.
+Some parts of the specification are already based on the work of other initiatives,
+e.g. the determination-related fields in the core specification.
+
+Related standards and working groups are:
+
+- [Adapt standard](https://adaptstandard.org), including their [WG17](https://github.com/ADAPT/Standard/issues/97)
+- [Varda FieldID](https://www.varda.ag/global-field-id)
+- [Deere Boundaries](https://developer.deere.com/dev-docs/boundaries)
+- [AgGateway](https://aggateway.org/), including their
+  [Locking in on Field Boundaries](https://aggateway.org/Portals/1010/WebSite/About%20Us/FIELD%20BOUNDARY%20FLYER%20122123.pdf?ver=2024-01-03-212959-590) initiative
+
+If you think we are missing relevant work here, we'd love to hear from you.
+Please get in touch by [opening an issue](https://github.com/fiboa/specification/issues/new)!
+
+## Contributing
 
 The fiboa community strives to provide a welcoming and transparent environment for all of the project’s participants.
 You can find additional information about our community best practices and collaborative development processes below:

diff --git a/best-practices/README.md b/best-practices/README.md
@@ -7,3 +7,10 @@
 
 All properties should be using snake case.
 For example a field for a land-use class should be named `landuse_class` instead of `landuseClass`.
+
+## Extension prefixes
+
+All properties in an extensions should have a common prefix.
+Extensions commonly use the colon (`:`) as separator between prefix and property name, e.g. `crop:name`.
+A single underscore (`_`) should be avoided to avoid conflicts with other property names (see [Casing](#casing)).
+Nevertheless, the separator can be chosen freely by extension authors.
diff --git a/core/README.md b/core/README.md
@@ -1,57 +1,88 @@
-# Core Specification
+# Core Specification <!-- omit in toc -->
 
-This specification describes the core data and metadata properties for both at the
-Collection and Feature level.
+This specification describes the core data and metadata properties that describe a fiboa Feature.
+The specification doesn't distinguish between collection-level and feature-level properties,
+common definitions are shared across these levels.
 
 - A Collection refers to a group of one or more features.
 - A Feature is a single field geometry with additional properties.
 
-> [!NOTE]
-> The Core Specification is still work in progress. Feedback is welcome!
+- **Schema:** <https://fiboa.github.io/specification/v0.3.0/schema.yaml>
 
-- **Schema:** <https://fiboa.github.io/specification/v0.2.0/schema.yaml>
+## Table of Contents <!-- omit in toc -->
 
-## Schema
+- [General Properties](#general-properties)
+  - [schemas](#schemas)
+  - [id](#id)
+  - [collection](#collection)
+  - [category](#category)
+- [Spatial Properties](#spatial-properties)
+  - [area / perimeter](#area--perimeter)
+- [Determination Properties](#determination-properties)
+  - [determination\_datetime](#determination_datetime)
+  - [determination\_method](#determination_method)
+- [Schema Language](#schema-language)
 
-The data types in the following document are defined in
-[fiboa Schema](https://github.com/fiboa/schema), v0.1.0.
+## General Properties
 
-fiboa Schema defines a (limited) set of data types and a vocabulary to express
-additional constraints for these data types.
-This allows to define a clear mapping between the core specification and its encodings.
+| Property Name | Data Type                       | Description |
+| ------------- | ------------------------------- | ----------- |
+| schemas       | object\<string, array\<string>> | **REQUIRED.** A list of schemas the collection implements. |
+| id            | string                          | **REQUIRED.** An identifier for the field. |
+| collection    | string                          | **REQUIRED.** The identifier of the collection. |
+| category      | array\<string>                  | A set of categories the field boundary belongs to. |
+
+### schemas
+
+The schemas the collection implements.
+Each schema must be a valid HTTP(S) URLs to an existing YAML files compliant to fiboa Schema.
+The schema for this specification (see above) is required to be provided.
+
+Each `collection` must have a single set of applicable schemas.
+The key of the dictionary must be equal to the value provided for the `collection` property.
 
-- [Data types](https://github.com/fiboa/schema/blob/v0.1.0/datatypes.md)
-- [Vocabulary](https://github.com/fiboa/schema/blob/v0.1.0/README.md#vocabulary)
+The schema URI for fiboa that is listed above is required to be present.
 
-## Collection
+**Example for `schemas`:**
 
-Collection-level metadata must be provided in an object that contains the properties below.
-The invidiual encodings may decide to embed the collection or make it available separately.
+This describes two collections `abc` and `xyz`.
 
-### Properties
+```json
+{
+  "abc": [
+    "https://fiboa.github.io/specification/v0.3.0/schema.yaml"
+  ],
+  "xyz": [
+    "https://fiboa.github.io/specification/v0.3.0/schema.yaml",
+    "https://fiboa.github.io/crop-extension/v0.1.0/schema.yaml",
+  ]
+}
+```
 
-| Property Name    | Data Type      | Description |
-| ---------------- | -------------- | ----------- |
-| fiboa_version    | string         | **REQUIRED.** Version number of the fiboa specification this entity implements. |
-| fiboa_extensions | array\<string> | A list of URIs to extensions this entity implements. |
+### id
 
-Generally, the version and the extensions must be uniform per Collection.
+It must be unique per collection, i.e. `collection` and `id` form a unique identifier.
 
-Other properties are also allowed to be provided, but are not described by this specification.
+### collection
 
-## Features
+A collection is a group of one or more features with a unique identifier, stored in the `collection` property.
 
-### General Properties
+Encodings may support to store properties that consists of the same value across all features at the collection-level.
+This de-duplicates data for more efficient resource usage, but only applies if more than two features are available for the collection.
+The specific location and behaviour of collection-level data is specified in the encoding-specific specifications.
 
-| Property Name | Data Type      | Description |
-| ------------- | -------------- | ----------- |
-| id            | string         | **REQUIRED.** A unique identifier for the field. It must be unique within the [Collection](#collection). |
-| collection    | string         | The identifier of the parent collection. |
-| category      | array\<string> | A set of categories the field boundary belongs to. |
+**Example:**
 
-**collection:** The collection identifier is usually only needed for merged datasets.
+You have two different field boundary datasets named `abc` (CC-0 licensed) and `xyz` (CC-BY-4.0 licensed).
+If you store the datasets separately, you can store the license in the collection-level data
+as the value for the property is the same for all features.
+Once you merged the two datasets, you must ensure that a unique identifier for the collection is provieded
+(here: `abc` and `xyz`) so that IDs are unique.
+Additionally, you have to add the license property on the feature-level as the licenses are now twofold.
 
-**category:** Choose any (unique) combination of the following values:
+### category
+
+Choose any (unique) combination of the following values:
 
 - `conceptual`: This boundary represents how the grower thinks of a field, and what they would share with service
   providers to allocate information at the highest level of the field concept within their operation.
@@ -65,7 +96,7 @@ Other properties are also allowed to be provided, but are not described by this
 
 The categories are based on the [definitions of the AgGateway initiative](https://aggateway.org/Portals/1010/WebSite/About%20Us/FIELD%20BOUNDARY%20FLYER%20122123.pdf?ver=2024-01-03-212959-590).
 
-### Spatial Properties
+## Spatial Properties
 
 | Property Name | Data Type    | Description |
 | ------------- | ------------ | ----------- |
@@ -74,29 +105,36 @@ The categories are based on the [definitions of the AgGateway initiative](https:
 | area          | float        | Area of the field, in hectares. Must be > 0 and <= 100,000. |
 | perimeter     | float        | Perimeter of the field, in meters. Must be > 0 and <= 125,000. |
 
-**area/perimeter:** These are derived attributes from the geometry itself,
+### area / perimeter
+
+These are derived attributes from the geometry itself,
 and must match the geometry's area/perimeter. If they do not match then the
 geometry should be considered canonical.
 Validators may flag the value as invalid if it exceeds a certain threshold.
 
-### Determination Properties
+## Determination Properties
 
-| Property Name          | Data Type | Description                                                  |
-| ---------------------- | --------- | ------------------------------------------------------------ |
-| determination_method   | string    | The boundary creation method, one of the values below.       |
-| determination_datetime | datetime  | The last timestamp at which the field did exist and was observed, in UTC. |
+| Property Name          | Data Type | Description |
+| ---------------------- | --------- | ----------- |
+| determination_method   | string    | The boundary creation method, one of the values below. |
+| determination_datetime | datetime  | The last timestamp at which the field did exist and was observed. |
 | determination_details  | string    | Further details about the determination, especially the methodology. |
 
-**determination_datetime**: In case the source of the information is an
-interval or a set of timestamps, use the end.
+### determination_datetime
+
+The last timestamp at which the field did exist and was observed, provided in the UTC timezone.
+
+In case the source of the information is an interval or a set of timestamps, use the end.
 For example, for ML you'd use the timestamp of the last image and not the
 timestamp of the actual execution.
 
 > [!NOTE]  
 > We define more temporal properties in the
 > [timestamps extension](https://github.com/fiboa/timestamps).
 
-**determination_method**: Must be one of the following values:
+### determination_method
+
+The determination method must be one of the following values:
 
 - `manual`: Hand created from imagery, e.g. using a tool to point and click on a map.
 - `surveyed`: Determined through a professional land survey measuring the actual distances and angles on the ground.
@@ -107,3 +145,15 @@ timestamp of the actual execution.
 
 The determination methods are based on the definitions of the [AgGateway initiative - WG17](https://aggateway.org/).
 The specific values have [not been published yet](https://github.com/fiboa/specification/issues/31).
+
+## Schema Language
+
+The schema language used for fiboa is [fiboa Schema](https://github.com/fiboa/schema), version 0.2.0.
+
+The data types in the tables above are defined in the document
+[Data Types](https://github.com/fiboa/schema/blob/v0.2.0/datatypes.md).
+
+fiboa Schema defines a (limited) set of data types and a
+[vocabulary](https://github.com/fiboa/schema/blob/v0.2.0/README.md#vocabulary)
+to express additional constraints for these data types.
+This allows to define a clear mapping between the core specification and its encodings.
diff --git a/core/schema/schema.yaml b/core/schema/schema.yaml
@@ -1,8 +1,25 @@
-$schema: https://fiboa.github.io/schema/v0.1.0/schema.json
+$schema: https://fiboa.github.io/schema/v0.3.0/schema.json
 required:
+  - schemas
   - id
+  - collection
   - geometry
+collection:
+  schemas: true
+  id: false
+  geometry: false
+  bbox: false
 properties:
+  schemas:
+    type: array
+    items:
+      type: string
+      format: uri
+      pattern: ^https?://
+    contains:
+      type: string
+      enum:
+        - https://fiboa.github.io/specification/v0.3.0/schema.yaml
   id:
     type: string
     minLength: 1