parseo 0.4.4__tar.gz

parseo-0.4.4/LICENSE.txt

@@ -0,0 +1,287 @@
+                      EUROPEAN UNION PUBLIC LICENCE v. 1.2
+                      EUPL © the European Union 2007, 2016
+
+This European Union Public Licence (the ‘EUPL’) applies to the Work (as defined
+below) which is provided under the terms of this Licence. Any use of the Work,
+other than as authorised under this Licence is prohibited (to the extent such
+use is covered by a right of the copyright holder of the Work).
+
+The Work is provided under the terms of this Licence when the Licensor (as
+defined below) has placed the following notice immediately following the
+copyright notice for the Work:
+
+        Licensed under the EUPL
+
+or has expressed by any other means his willingness to license under the EUPL.
+
+1. Definitions
+
+In this Licence, the following terms have the following meaning:
+
+- ‘The Licence’: this Licence.
+
+- ‘The Original Work’: the work or software distributed or communicated by the
+  Licensor under this Licence, available as Source Code and also as Executable
+  Code as the case may be.
+
+- ‘Derivative Works’: the works or software that could be created by the
+  Licensee, based upon the Original Work or modifications thereof. This Licence
+  does not define the extent of modification or dependence on the Original Work
+  required in order to classify a work as a Derivative Work; this extent is
+  determined by copyright law applicable in the country mentioned in Article 15.
+
+- ‘The Work’: the Original Work or its Derivative Works.
+
+- ‘The Source Code’: the human-readable form of the Work which is the most
+  convenient for people to study and modify.
+
+- ‘The Executable Code’: any code which has generally been compiled and which is
+  meant to be interpreted by a computer as a program.
+
+- ‘The Licensor’: the natural or legal person that distributes or communicates
+  the Work under the Licence.
+
+- ‘Contributor(s)’: any natural or legal person who modifies the Work under the
+  Licence, or otherwise contributes to the creation of a Derivative Work.
+
+- ‘The Licensee’ or ‘You’: any natural or legal person who makes any usage of
+  the Work under the terms of the Licence.
+
+- ‘Distribution’ or ‘Communication’: any act of selling, giving, lending,
+  renting, distributing, communicating, transmitting, or otherwise making
+  available, online or offline, copies of the Work or providing access to its
+  essential functionalities at the disposal of any other natural or legal
+  person.
+
+2. Scope of the rights granted by the Licence
+
+The Licensor hereby grants You a worldwide, royalty-free, non-exclusive,
+sublicensable licence to do the following, for the duration of copyright vested
+in the Original Work:
+
+- use the Work in any circumstance and for all usage,
+- reproduce the Work,
+- modify the Work, and make Derivative Works based upon the Work,
+- communicate to the public, including the right to make available or display
+  the Work or copies thereof to the public and perform publicly, as the case may
+  be, the Work,
+- distribute the Work or copies thereof,
+- lend and rent the Work or copies thereof,
+- sublicense rights in the Work or copies thereof.
+
+Those rights can be exercised on any media, supports and formats, whether now
+known or later invented, as far as the applicable law permits so.
+
+In the countries where moral rights apply, the Licensor waives his right to
+exercise his moral right to the extent allowed by law in order to make effective
+the licence of the economic rights here above listed.
+
+The Licensor grants to the Licensee royalty-free, non-exclusive usage rights to
+any patents held by the Licensor, to the extent necessary to make use of the
+rights granted on the Work under this Licence.
+
+3. Communication of the Source Code
+
+The Licensor may provide the Work either in its Source Code form, or as
+Executable Code. If the Work is provided as Executable Code, the Licensor
+provides in addition a machine-readable copy of the Source Code of the Work
+along with each copy of the Work that the Licensor distributes or indicates, in
+a notice following the copyright notice attached to the Work, a repository where
+the Source Code is easily and freely accessible for as long as the Licensor
+continues to distribute or communicate the Work.
+
+4. Limitations on copyright
+
+Nothing in this Licence is intended to deprive the Licensee of the benefits from
+any exception or limitation to the exclusive rights of the rights owners in the
+Work, of the exhaustion of those rights or of other applicable limitations
+thereto.
+
+5. Obligations of the Licensee
+
+The grant of the rights mentioned above is subject to some restrictions and
+obligations imposed on the Licensee. Those obligations are the following:
+
+Attribution right: The Licensee shall keep intact all copyright, patent or
+trademarks notices and all notices that refer to the Licence and to the
+disclaimer of warranties. The Licensee must include a copy of such notices and a
+copy of the Licence with every copy of the Work he/she distributes or
+communicates. The Licensee must cause any Derivative Work to carry prominent
+notices stating that the Work has been modified and the date of modification.
+
+Copyleft clause: If the Licensee distributes or communicates copies of the
+Original Works or Derivative Works, this Distribution or Communication will be
+done under the terms of this Licence or of a later version of this Licence
+unless the Original Work is expressly distributed only under this version of the
+Licence — for example by communicating ‘EUPL v. 1.2 only’. The Licensee
+(becoming Licensor) cannot offer or impose any additional terms or conditions on
+the Work or Derivative Work that alter or restrict the terms of the Licence.
+
+Compatibility clause: If the Licensee Distributes or Communicates Derivative
+Works or copies thereof based upon both the Work and another work licensed under
+a Compatible Licence, this Distribution or Communication can be done under the
+terms of this Compatible Licence. For the sake of this clause, ‘Compatible
+Licence’ refers to the licences listed in the appendix attached to this Licence.
+Should the Licensee's obligations under the Compatible Licence conflict with
+his/her obligations under this Licence, the obligations of the Compatible
+Licence shall prevail.
+
+Provision of Source Code: When distributing or communicating copies of the Work,
+the Licensee will provide a machine-readable copy of the Source Code or indicate
+a repository where this Source will be easily and freely available for as long
+as the Licensee continues to distribute or communicate the Work.
+
+Legal Protection: This Licence does not grant permission to use the trade names,
+trademarks, service marks, or names of the Licensor, except as required for
+reasonable and customary use in describing the origin of the Work and
+reproducing the content of the copyright notice.
+
+6. Chain of Authorship
+
+The original Licensor warrants that the copyright in the Original Work granted
+hereunder is owned by him/her or licensed to him/her and that he/she has the
+power and authority to grant the Licence.
+
+Each Contributor warrants that the copyright in the modifications he/she brings
+to the Work are owned by him/her or licensed to him/her and that he/she has the
+power and authority to grant the Licence.
+
+Each time You accept the Licence, the original Licensor and subsequent
+Contributors grant You a licence to their contributions to the Work, under the
+terms of this Licence.
+
+7. Disclaimer of Warranty
+
+The Work is a work in progress, which is continuously improved by numerous
+Contributors. It is not a finished work and may therefore contain defects or
+‘bugs’ inherent to this type of development.
+
+For the above reason, the Work is provided under the Licence on an ‘as is’ basis
+and without warranties of any kind concerning the Work, including without
+limitation merchantability, fitness for a particular purpose, absence of defects
+or errors, accuracy, non-infringement of intellectual property rights other than
+copyright as stated in Article 6 of this Licence.
+
+This disclaimer of warranty is an essential part of the Licence and a condition
+for the grant of any rights to the Work.
+
+8. Disclaimer of Liability
+
+Except in the cases of wilful misconduct or damages directly caused to natural
+persons, the Licensor will in no event be liable for any direct or indirect,
+material or moral, damages of any kind, arising out of the Licence or of the use
+of the Work, including without limitation, damages for loss of goodwill, work
+stoppage, computer failure or malfunction, loss of data or any commercial
+damage, even if the Licensor has been advised of the possibility of such damage.
+However, the Licensor will be liable under statutory product liability laws as
+far such laws apply to the Work.
+
+9. Additional agreements
+
+While distributing the Work, You may choose to conclude an additional agreement,
+defining obligations or services consistent with this Licence. However, if
+accepting obligations, You may act only on your own behalf and on your sole
+responsibility, not on behalf of the original Licensor or any other Contributor,
+and only if You agree to indemnify, defend, and hold each Contributor harmless
+for any liability incurred by, or claims asserted against such Contributor by
+the fact You have accepted any warranty or additional liability.
+
+10. Acceptance of the Licence
+
+The provisions of this Licence can be accepted by clicking on an icon ‘I agree’
+placed under the bottom of a window displaying the text of this Licence or by
+affirming consent in any other similar way, in accordance with the rules of
+applicable law. Clicking on that icon indicates your clear and irrevocable
+acceptance of this Licence and all of its terms and conditions.
+
+Similarly, you irrevocably accept this Licence and all of its terms and
+conditions by exercising any rights granted to You by Article 2 of this Licence,
+such as the use of the Work, the creation by You of a Derivative Work or the
+Distribution or Communication by You of the Work or copies thereof.
+
+11. Information to the public
+
+In case of any Distribution or Communication of the Work by means of electronic
+communication by You (for example, by offering to download the Work from a
+remote location) the distribution channel or media (for example, a website) must
+at least provide to the public the information requested by the applicable law
+regarding the Licensor, the Licence and the way it may be accessible, concluded,
+stored and reproduced by the Licensee.
+
+12. Termination of the Licence
+
+The Licence and the rights granted hereunder will terminate automatically upon
+any breach by the Licensee of the terms of the Licence.
+
+Such a termination will not terminate the licences of any person who has
+received the Work from the Licensee under the Licence, provided such persons
+remain in full compliance with the Licence.
+
+13. Miscellaneous
+
+Without prejudice of Article 9 above, the Licence represents the complete
+agreement between the Parties as to the Work.
+
+If any provision of the Licence is invalid or unenforceable under applicable
+law, this will not affect the validity or enforceability of the Licence as a
+whole. Such provision will be construed or reformed so as necessary to make it
+valid and enforceable.
+
+The European Commission may publish other linguistic versions or new versions of
+this Licence or updated versions of the Appendix, so far this is required and
+reasonable, without reducing the scope of the rights granted by the Licence. New
+versions of the Licence will be published with a unique version number.
+
+All linguistic versions of this Licence, approved by the European Commission,
+have identical value. Parties can take advantage of the linguistic version of
+their choice.
+
+14. Jurisdiction
+
+Without prejudice to specific agreement between parties,
+
+- any litigation resulting from the interpretation of this License, arising
+  between the European Union institutions, bodies, offices or agencies, as a
+  Licensor, and any Licensee, will be subject to the jurisdiction of the Court
+  of Justice of the European Union, as laid down in article 272 of the Treaty on
+  the Functioning of the European Union,
+
+- any litigation arising between other parties and resulting from the
+  interpretation of this License, will be subject to the exclusive jurisdiction
+  of the competent court where the Licensor resides or conducts its primary
+  business.
+
+15. Applicable Law
+
+Without prejudice to specific agreement between parties,
+
+- this Licence shall be governed by the law of the European Union Member State
+  where the Licensor has his seat, resides or has his registered office,
+
+- this licence shall be governed by Belgian law if the Licensor has no seat,
+  residence or registered office inside a European Union Member State.
+
+Appendix
+
+‘Compatible Licences’ according to Article 5 EUPL are:
+
+- GNU General Public License (GPL) v. 2, v. 3
+- GNU Affero General Public License (AGPL) v. 3
+- Open Software License (OSL) v. 2.1, v. 3.0
+- Eclipse Public License (EPL) v. 1.0
+- CeCILL v. 2.0, v. 2.1
+- Mozilla Public Licence (MPL) v. 2
+- GNU Lesser General Public Licence (LGPL) v. 2.1, v. 3
+- Creative Commons Attribution-ShareAlike v. 3.0 Unported (CC BY-SA 3.0) for
+  works other than software
+- European Union Public Licence (EUPL) v. 1.1, v. 1.2
+- Québec Free and Open-Source Licence — Reciprocity (LiLiQ-R) or Strong
+  Reciprocity (LiLiQ-R+).
+
+The European Commission may update this Appendix to later versions of the above
+licences without producing a new version of the EUPL, as long as they provide
+the rights granted in Article 2 of this Licence and protect the covered Source
+Code from exclusive appropriation.
+
+All other changes or additions to this Appendix require the production of a new
+EUPL version.

parseo-0.4.4/MANIFEST.in

@@ -0,0 +1 @@
+recursive-include src/parseo/schemas *filename_v*.json

parseo-0.4.4/PKG-INFO

@@ -0,0 +1,402 @@
+Metadata-Version: 2.4
+Name: parseo
+Version: 0.4.4
+Summary: Filename parser/assembler for satellite data
+Author-email: Matteo Mattiuzzi <matteo@mattiuzzi.com>
+License: EUPL-1.2
+Project-URL: Homepage, https://github.com/copernicus-land/parsEO
+Project-URL: Repository, https://github.com/copernicus-land/parsEO.git
+Project-URL: Issues, https://github.com/copernicus-land/parsEO/issues
+Project-URL: Changelog, https://github.com/copernicus-land/parsEO/releases
+Keywords: satellite,remote-sensing,filenames,sentinel,parsing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: European Union Public Licence 1.2 (EUPL 1.2)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: build>=1.4.4
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Provides-Extra: web
+Requires-Dist: fastapi; extra == "web"
+Requires-Dist: uvicorn; extra == "web"
+Dynamic: license-file
+
+::: {align="center"}
+# parsEO
+
+**parsEO** is a Python toolkit that parses existing Earth Observation filenames into structured metadata and assembles new filenames from validated fields. Filename rules live in JSON schemas, turning the repository into a single source of truth for product nomenclature.
+:::
+
+## Why parsEO?
+
+-   **Bidirectional workflows** – convert filenames to Python dictionaries and rebuild filenames from the same fields.
+-   **Schema-driven** – JSON schemas define every product token, validation rule, and STAC link. Drop in a new schema file and it is discovered automatically.
+-   **Extensible** – contributions focus on data, not glue code. Adding support for a new mission only requires a schema.
+
+## Supported product families
+
+-   **Sentinel missions** – S1, S2, S3, S4, S5P, S6
+-   **Landsat** – LT04, LT05, LE07, LC08, LC09
+-   **NASA MODIS** – Terra and Aqua MODIS products
+-   **EUMETSAT missions** – MTG, Metop
+-   **Copernicus Land Monitoring Service (CLMS)**
+    -   Corine Land Cover (CLC) and CLC+ Raster
+    -   European Ground Motion Service (EGMS) Level 2 basic/calibrated products, Level 3 velocity grid, and GNSS model
+    -   Urban Atlas Land Cover / Land Use
+    -   High Resolution Vegetation Phenology & Productivity (HR-VPP): Seasonal Trajectories (PPI) and Vegetation Indices (FAPAR, LAI, NDVI, PPI, FCOVER, DMP)
+    -   High Resolution Water & Snow / Ice (HR-WSI): CC, FSC, GFSC, ICD, SWS, WDS, WIC, WIC-COMB, SP_S2, SP_COMB
+    -   High Resolution Layers (HRL): Forest Type, Grassland, Imperviousness, Non-Vegetated Land Cover Characteristics, Tree Cover Density, Water & Wetness, Small Woody Features
+
+## Installation
+
+``` bash
+pip install parseo
+```
+
+For development installs:
+
+``` bash
+git clone https://github.com/copernicus-land/parsEO.git
+cd parsEO
+pip install -e .
+```
+
+Confirm the CLI is available:
+
+``` bash
+parseo --version
+```
+
+## Quick start
+
+### Parse a filename
+
+``` python
+from parseo import parse_auto
+
+name = "S2B_MSIL2A_20241123T224759_N0511_R101_T03VUL_20241123T230829.SAFE"
+result = parse_auto(name)
+
+print(result.valid)   # True
+print(result.fields)  # structured dict of extracted fields
+```
+
+Another example using a MODIS filename:
+
+``` python
+from parseo import parse_auto
+
+name = "MOD09GA.A2021123.h18v04.006.2021132234506.hdf"
+result = parse_auto(name)
+
+print(result.fields["platform"])  # MOD
+print(result.fields["product"])   # 09
+print(result.fields["variant"])   # GA
+```
+
+The MODIS schema advertises the Processing, Sat, Raster, and Electro-Optical STAC extensions, enabling automated STAC metadata generation (`processing`, `sat`, `raster`, `eo`).
+
+### Assemble a filename
+
+``` python
+from parseo import assemble, assemble_auto
+
+fields = {
+    "platform": "S2B",
+    "instrument": "MSI",
+    "processing_level": "L2A",
+    "sensing_datetime": "20241123T224759",
+    "processing_baseline": "N0511",
+    "relative_orbit": "R101",
+    "tile_id": "T03VUL",  # MGRS tile (TxxYYY, e.g. T32TNS)
+    "generation_datetime": "20241123T230829",
+    "extension": "SAFE",
+}
+
+assemble_auto(fields)
+# 'S2B_MSIL2A_20241123T224759_N0511_R101_T03VUL_20241123T230829.SAFE'
+
+assemble(fields, family="S2")
+# Uses the default (current) Sentinel-2 schema for quicker resolution.
+
+assemble(fields, family="S2", version="1.0.0")
+# Lock both family and schema version explicitly.
+```
+
+To force a specific schema file:
+
+``` python
+from pathlib import Path
+from parseo import assemble
+
+schema_path = Path("src/parseo/schemas/copernicus/sentinel/s2/s2_filename_v1_0_0.json")
+filename = assemble(fields, schema_path=schema_path)
+```
+
+`parse_auto` reports the schema version and lifecycle status that were used:
+
+``` python
+from parseo import parse_auto
+
+result = parse_auto("S2B_MSIL2A_20241123T224759_N0511_R101_T03VUL_20241123T230829.SAFE")
+print(result.version)  # '1.0.0'
+print(result.status)   # 'current'
+```
+
+### Command-line interface
+
+The same functionality is exposed through the CLI.
+
+``` bash
+# Parse a filename
+parseo parse S2B_MSIL2A_20241123T224759_N0511_R101_T03VUL_20241123T230829.SAFE
+
+# Parse a Copernicus Land Monitoring Service (CLMS) filename
+parseo parse ST_20240101T123045_S2_E15N45-03035-010m_V100_PPI.tif
+
+# Parse and write the JSON response to a file
+parseo parse ST_20240101T123045_S2_E15N45-03035-010m_V100_PPI.tif --output result.json
+
+# Assemble from the saved JSON document. The CLI automatically
+# extracts the `fields` entry produced by `parseo parse`.
+cat result.json | parseo assemble --family copernicus:clms:hr-vpp:st --fields-json -
+
+# Pipe the parse result directly into assemble
+parseo parse ST_20240101T123045_S2_E15N45-03035-010m_V100_PPI.tif \
+  | parseo assemble --family copernicus:clms:hr-vpp:st
+
+# Assemble the same CLMS filename from key=value pairs
+parseo assemble
+  product=ST
+  timestamp=20240101T123045 
+  sensor=S2
+  tile_id=E15N45
+  epsg_code=03035
+  resolution=010m
+  version=V100
+  variable=PPI
+  extension=tif
+```
+
+### Discover available schemas
+
+List every schema that ships with parsEO, including its fully qualified `schema_id`, semantic version, lifecycle status, and file location:
+
+``` bash
+parseo list-schemas
+```
+
+The command prints a table summarizing all discovered schemas, making it easy to confirm which versions are available before parsing or assembling filenames. The first column shows the complete namespace (for example `copernicus:clms:hrl:vlcc`), so you can see exactly where a product sits inside the Copernicus hierarchy.
+
+List only the schemas that are marked as `current` with the built-in filter (works on every platform):
+
+``` bash
+parseo list-schemas --status current
+```
+
+To inspect a single family in the summary table, provide the short family name explicitly. You can also pass a namespace prefix to see every schema beneath it:
+
+``` bash
+parseo list-schemas --family S2
+parseo list-schemas --family copernicus
+parseo list-schemas --family copernicus:clms:hrl
+```
+
+For the full schema metadata (fields, examples, etc.), use `schema-info`:
+
+``` bash
+parseo schema-info S2
+```
+
+The JSON response includes the schema's semantic version and lifecycle status so
+you can immediately tell which release you are viewing. To inspect an archived
+version, provide the version number explicitly:
+
+``` bash
+parseo schema-info --version 1.0.0 CLC
+```
+
+### Working with specific schema versions
+
+When multiple schema versions are present, parsEO chooses the one whose `status` is `"current"`. If none are marked current, the highest `schema_version` wins. You can inspect historical schemas with `parseo schema-info --version <x.y.z> <family>` and you can always pin a schema by passing `schema_path` to `assemble` or `parse`.
+
+## Authoring new Schema
+
+Adding a schema requires only a JSON document under `src/parseo/schemas/`. Start from an existing product schema or the skeleton in `template/`.
+
+-   **Create the product directory** – `src/parseo/schemas/<family>/<mission>/<product>/` (only the family level is mandatory).
+
+-   **Write the versioned schema file** – `<product>_filename_vX_Y_Z.json` with required metadata (`schema_id`, `schema_version`, `status`, optional `stac_version`, `stac_extensions`, and `description`).
+
+-   **Maintain versions** — mark the latest schema as `"current"` and move older ones to `"deprecated"` (or similar). parsEO uses these flags to pick defaults.
+
+    **Schema versioning policy:** Schemas at version `0.0.0` are provisional — their patterns and field definitions may change without notice. Once a product's naming convention is finalised (typically when it reaches CDSE production), the schema should be promoted to `1.0.0` to signal a stable, supported contract.
+
+### Container Object `fields`
+
+**`fields`** is a container object to define filename tokens and translation mechanisms from/to STAC. Each `property` combines JSON Schema keywords (`type`, `pattern`, `enum`, …) and optional documentation. The `property name` is the variable name used by the `template` container and unless a `stac_map` is applied also what is retrieved by `parseo parse` or fed into `parseo assemble`.
+
+``` json
+"fields": { 
+  "property-1": {
+    "type": "string", 
+    "enum": ["A","B"], 
+    "description": "descripton of property 1"
+  },
+  "property-2": {
+    "type": "string", 
+    "pattern": "^(\d{8}T\d{6})$", 
+    "description": "descripton of property 2"
+  },
+  ...
+}
+```
+
+#### `type`
+
+The keyword `type` is currently set to "string" by default, and used as best practice.
+
+#### `enum` or `pattern`
+
+-   Use `enum` for short, controlled vocabularies such as file extensions or processing modes (`["A","B"]`). It keeps validation strict and self-documenting.
+-   Use `pattern` for structured tokens like timestamps (`^\d{8}T\d{6}$`), version identifiers (`^V\d{3}$`), or grid identifiers (`^h\d{2}v\d{2}$`).
+
+#### `oneOf`
+
+Use `oneOf` to express mutually exclusive validation branches for a single field. Each branch can provide its own JSON Schema keywords, enabling concise modelling of tokens that admit multiple formats. For example, a `variant` token may allow either a fixed set of legacy values or a future-proof pattern:
+
+``` json
+"variant": {
+  "type": "string",
+  "oneOf": [
+    {"enum": ["A", "B", "C"]},
+    {"pattern": "^X\d{2}$"},
+    {"pattern": "^z\d{4}$"}
+  ],
+  "description": "Legacy letters or experimental codes"
+}
+```
+
+When `parseo parse` runs, the value is checked against each branch in order until one succeeds. `parseo assemble` accepts any value satisfying at least one branch, allowing schemas to stay expressive without duplicating fields.
+
+#### `stac_map`
+
+Functionality to connect filename tokens to STAC properties in case of incompatibility. In the following example `parseo parse` matches the filename field `prefix` but returns the STAC compliant `platform` and `instrument`. `parseo assemble` must be provided with `platform` and `instrument` and converts it to the correct `prefix` as defined by the filename `template`.
+
+``` json
+"prefix": {
+  "type": "string",
+  "pattern": "^(MOD|MYD|MCD)$",
+  "stac_map": {
+    "MOD": {
+      "platform": "Terra", 
+      "instrument": "MODIS"
+    },
+    "MYD": {
+      "platform": "Aqua", 
+      "instrument": "MODIS"
+    },
+    "MCD": {
+      "platform": "Combined", 
+      "instrument": "MODIS"
+    }
+  }
+}
+```
+
+
+#### Container Object `template`
+A filename is assembled/parsed based on the definition put into `template` container object. E.g.:
+
+``` json
+"template": "{variable}-C{reference_year}_R{resolution}_{tile_id}{epsg_code}_{version}[.{extension}]"
+```
+
+`fields` are added to the `template` using the `{property name}`. The template further decides for the fields are arranged and how they are separated from each other. Further it is possible to ad permanent elements as well, e.g. adding a prefix `C` to the `{reference_year} = C{reference_year}` to match e.g. 'C2012'. This can be particularly useful if you are interested in only parts of the field, e.g. by doping `EPSG{epsg_code}` you fetch only the code itself. This can also be a regex, e.g. `..._(S|C){reference_year}_...`.
+
+Optional filenames must be encapsulated in `[]`. E.g. `[.{extension}]`
+
+#### Container Object `examples` 
+
+Populate `"examples"` with valid filenames covering typical combinations of optional tokens. Test routines will run the examples to assess the proper functioning.
+
+### Test round-trips
+
+run `parseo parse <filename>` and `parseo assemble --schema <schema_path>` to confirm the schema behaves as expected.
+
+### Run unit tests
+
+Install the pytest python package.
+
+from the top-level directory, run `pytest` to launch all tests, or e.g `pytest tests/test_schema_examples_round_trip.py`
+
+### Run as API
+
+parsEO functions can be exposed through a web service. The example below uses [FastAPI](https://fastapi.tiangolo.com), which provides an automatic Swagger UI for trying out the endpoints.
+
+``` python
+# Safe to file: main.py
+from fastapi import FastAPI
+from parseo import assemble, parse_auto
+
+app = FastAPI()
+
+@app.get("/parse")
+def parse_endpoint(name: str):
+    res = parse_auto(name)
+    return res
+
+@app.post("/assemble")
+def assemble_endpoint(schema: str, fields: dict):
+    filename = assemble(fields, schema_path=schema)
+    return {"filename": filename}
+```
+
+Install fastapi and uvicorn (in a python virtual environment):
+
+``` bash
+python3 -m venv .venv
+source .venv/bin/activate
+```
+
+Install the required dependencies (fastapi and uvicorn):
+
+``` bash
+(.venv) pip install fastapi uvicorn[standard]
+```
+
+from the console inside the same directory start the app:
+
+``` bash
+(.venv) python -m uvicorn main:app --reload
+```
+
+Open <http://127.0.0.1:8000/docs> to access Swagger UI:
+
+The interactive page lets you call `/parse` and `/assemble` directly from the browser to verify the API.
+
+
+## Contributing
+
+-   Place new schemas under `src/parseo/schemas/<product_family>/`.
+-   Include at least one positive example in each schema file.
+-   Run the test-suite with `pytest` (and `ruff check .` for linting) before opening a pull request.
+-   Submit a pull request describing the new products or fixes.
+
+## License
+
+This project is licensed under the [European Union Public Licence v1.2](LICENSE.txt).