Update changelog and spec version for v1.2-rc.2 (#485)

* Update changelog and spec version for rc.2

* Apply suggestions from code review

* Add biased selection of recent contributors to AUTHORS list

* Add citation for latest preprint in README

* Update CHANGELOG and add implementation notes

* Add new links out to schemas and specification

* Update AUTHORS

* Add link to future spec builds

* Apply suggestions from code review

Co-authored-by: Andrius Merkys <[email protected]>
Co-authored-by: Antanas Vaitkus <[email protected]>

* Apply suggestions from code review

* Update CHANGELOG.md

* Apply suggestions from code review

Co-authored-by: Andrius Merkys <[email protected]>
Co-authored-by: Antanas Vaitkus <[email protected]>

* Set version to rc.2

* Improve license description

Co-authored-by: Rickard Armiento <[email protected]>

* Apply suggestions from code review

Co-authored-by: Antanas Vaitkus <[email protected]>

---------

Co-authored-by: Andrius Merkys <[email protected]>
Co-authored-by: Antanas Vaitkus <[email protected]>
Co-authored-by: Rickard Armiento <[email protected]>

AUTHORS

@@ -5,14 +5,19 @@ The OPTIMADE API has been developed with contributions by the participants of th
 - the CECAM in Lausanne, Switzerland (virtually) 2020-06-08 to 2020-06-12
 - the CECAM in Lausanne, Switzerland (virtually) 2021-06-07 to 2021-06-11
 - the CECAM in Lausanne, Switzerland 2022-05-30 to 2022-06-03
+- the CECAM in Lausanne, Switzerland 2023-06-05 to 2023-06-09
 
-Contributors to the development of the OPTIMADE specification and implementation in alphabetical order:
+Initial and major contributors to the development of the OPTIMADE specification and implementation in alphabetical order:
 Casper Andersen
+Oskar Andersson
 Thomas Archer
 Rickard Armiento
 Rossella Aversa
+Daniel Beltrán
 Johan Bergsma
 Evgeny Blokhin
+Tara Boland
+Sara Bonella
 Kamal Choudhary
 Pauline Colinet
 Gareth Conduit
@@ -21,6 +26,7 @@ Davide Di Stefano
 Alexander Dorsk
 Claudia Draxl
 Shyam Dwaraknath
+Kristjan Eimre
 Suleyman Er
 Marco Esters
 Matthew Evans
@@ -39,11 +45,14 @@ Jens Hummelshoej
 Karsten W. Jacobsen
 Ankit Kariryaa
 Boris Kozinsky
+Adam Krajewski
 Snehal Kumbhar
 Mohan Liu
+Zi-Kui Liu
 Nicola Marzari
 Andrius Merkys
 Fawzi Mohamed
+Jens Jørgen Mortensen
 Andrew Morris
 Arash Mostofi
 Corey Oses
@@ -68,3 +77,4 @@ Chris Wolverton
 Michael Wu
 Yibin Xu
 Xiaoyu Yang
+Jusong Yu

CHANGELOG.md

@@ -1,30 +1,50 @@
 # Changelog
 
-## v1.2.0-rc.1 (December 2022)
+## v1.2.0 (April 2024)
 
-This is the first release candidate of v1.2.0 of the OPTIMADE API specification.
-It should contain all of the new features in the specification, but their implementation may be modified in the final release.
 
-Note: The OpenAPI schemas distributed in `./schemas` have not yet been modified with the new features 1.2.0.
+This release adds significant but optional new functionality to the specification; it also provides several clarifications to existing behaviour.
 
-This minor release adds significant but optional new functionality to the specification, as well as providing several clarifications to existing behaviour.
+Minor OPTIMADE releases are always intended to be backwards-compatible for clients, meaning that any client code written for v1.1 should continue to work.
+Although the majority of features added in this release are optional for servers, there are a couple of mandatory format additions that are discussed below in the notes for implementations.
+We have clarified our approach to versioning explicitly in the specification under [Versioning of this standard](https://github.com/Materials-Consortia/OPTIMADE/blob/v1.2.0/optimade.rst#versioning-of-this-standard).
+
+For a more academic summary of the changes, please see our preprint: [arXiv:2402.00572](https://doi.org/10.48550/arXiv.2402.00572).
+
+In addition to the specification document itself, machine-readable schemas from this repository can now be found hosted at [schemas.optimade.org](https:///schemas.optimade.org), and HTML builds of the specification can be found at [specification.optimade.org](https://specification.optimade.org).
 
 ### New features
 
-- **Property definitions** ([#376](https://github.com/Materials-Consortia/OPTIMADE/pull/376)).
-A new section titled [Property Definitions](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#property-definitions) has been added to the specification which significantly extends the way in which implementations can define and describe the custom properties they serve, including URIs, unit definitions, API support levels (for querying and sorting) as well as full support for JSON Schema constructs for describing the JSON representation of the property.
-- **Files endpoint** ([#360](https://github.com/Materials-Consortia/OPTIMADE/pull/360)).
-The `/files` endpoint and corresponding [`files` entry
-type](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#files-entries) has been added to provide a robust way of linking entries to arbitrary file-based data relevant to the entry, such as alternative crystal structure representation formats, input or output files from computational procedures, or experimental data files.
-- **Boolean values** ([#348](https://github.com/Materials-Consortia/OPTIMADE/pull/348)).
-[Boolean values](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#comparisons-of-boolean-values) were overlooked in the first version of the filter grammar as no OPTIMADE fields required them.
+- **Property definitions** ([#376](https://github.com/Materials-Consortia/OPTIMADE/pull/376)): A new section titled [Property Definitions](https://github.com/Materials-Consortia/OPTIMADE/blob/v1.2.0/optimade.rst#property-definitions) has been added to the specification which significantly extends the way in which implementations can define and describe the custom properties they serve, including URIs, unit definitions, API support levels (for querying and sorting) as well as full support for JSON Schema constructs for describing the JSON representation of the property. These definitions form the basis of a new machine-readable form of the OPTIMADE specification found in the main repository and served at [schemas.optimade.org](https://schemas.optimade.org).
+- **Namespace prefixes for definitions** ([#473](https://github.com/Materials-Consortia/OPTIMADE/pull/473)): The mechanism for providers to define custom properties under their own namespace/prefix has been extended to allow implementations to share common definitions. These so-called definition namespaces can be registered as providers in their own right and can serve property definitions in the new format.
+- **Partial data** ([#467](https://github.com/Materials-Consortia/OPTIMADE/pull/467)): Adds a mechanism and format for streaming, paginating or slicing individual properties within entries.
+- **Per entry/property metadata** ([#463](https://github.com/Materials-Consortia/OPTIMADE/pull/463)): Added a mechanism for providing metadata specific to a given entry or property.
+- **Files endpoint** ([#360](https://github.com/Materials-Consortia/OPTIMADE/pull/360)): The [`files` entry type](https://github.com/Materials-Consortia/OPTIMADE/blob/v1.2.0/optimade.rst#files-entries) has been added to provide a robust way of linking entries to arbitrary file-based data relevant to the entry, such as alternative crystal structure representation formats, input or output files from computational procedures, or experimental data files.
+- **Symmetry operation specification and space group fields** ([#480](https://github.com/Materials-Consortia/OPTIMADE/pull/480), [#405](https://github.com/Materials-Consortia/OPTIMADE/pull/405), [#464](https://github.com/Materials-Consortia/OPTIMADE/pull/464)): Several fields have been added to the `structures` entry type to fully describe symmetry. Symmetry operations can be provided explicitly in `space_group_symmetry_operations_xyz`, as well as space group specifications in various forms: `space_group_symbol_hall`, `space_group_symbol_hermann_mauguin`, `space_group_symbol_hermann_mauguin_extended`, `space_group_it_number`.
+- **Database licenses** ([#414](https://github.com/Materials-Consortia/OPTIMADE/pull/414),[#497](https://github.com/Materials-Consortia/OPTIMADE/pull/497)): Several fields have been added to programmatically describe the licensing status of data served by OPTIMADE APIs. A database-wide license can be provided as a set of [SPDX identifiers](https://spdx.org/licenses/) in `available_licenses`, with a related field `available_licenses_for_entries` specifying specifically which licenses apply to individual entries and other non-substantial extracts from the database for cases where these differ from the database-wide licenses. The global field `license` can be used point to a human-readable license page (external or otherwise) that explains any caveats to the licensing arrangement.
+- **Database metadata field** ([#424](https://github.com/Materials-Consortia/OPTIMADE/pull/424)): Added an additional metadata field `database` for providing a human-readable description of a given database.
+- **Backoff time** ([#411](https://github.com/Materials-Consortia/OPTIMADE/pull/411)): Databases can now request ahead of time that clients apply a particular rate limit or back-off time via the `request_delay` metadata field.
+
+### Patches
+
+- **Fuzzy comparisons on lists** ([#415](https://github.com/Materials-Consortia/OPTIMADE/pull/415)):
+String comparisons like `CONTAINS`, `STARTS WITH` and `ENDS WITH` are now compatible with list filter operations like `HAS`, `HAS ALL` etc.
+- **Boolean values** ([#348](https://github.com/Materials-Consortia/OPTIMADE/pull/348)):
+[Boolean values](https://github.com/Materials-Consortia/OPTIMADE/blob/v1.2.0/optimade.rst#comparisons-of-boolean-values) were overlooked in the first version of the filter grammar as no OPTIMADE fields required them.
 This functionality has been introduced for boolean fields using the syntax `TRUE` and `FALSE`.
 Only strict equality (`=`) and inequality (`!=`) comparisons on individual fields are supported.
-- **Fuzzy comparisons on lists** ([#415](https://github.com/Materials-Consortia/OPTIMADE/pull/415))
-String comparisons like `CONTAINS`, `STARTS WITH` and `ENDS WITH` are now compatible with list filter operations like `HAS`, `HAS ALL` etc.
-- **Backoff time** ([#411](https://github.com/Materials-Consortia/OPTIMADE/pull/411)):
-- **Database licenses** ([#414](https://github.com/Materials-Consortia/OPTIMADE/pull/414)):
-- **Symmetry data** ([#405](https://github.com/Materials-Consortia/OPTIMADE/pull/405)):
+- **Compatibility with JSON:API v1.1** ([#461](https://github.com/Materials-Consortia/OPTIMADE/pull/461)): References to JSON:API v1.0 have been updated to v1.1.
+- Typo, formatting and code snippet fixes.
+
+### Notes for implementations
+
+As discussed above, the majority of this release involves the addition of more expressive metadata fields for property definitions, definition namespaces shared across providers, and licensing information, as well as mechanisms for serving files and partial data responses (for large entries, e.g., giant structures).
+We hope that the machine-readable schemas and property definitions now available at [schemas.optimade.org](https://schemas.optimade.org) will make implementing the specification much easier.
+
+The mandatory format changes required to support v1.2 are limited to the following:
+
+- `/info/<entry_type>` endpoints MUST now have a top-level `id` and `type` field, e.g., the `/info/structures` MUST now serve `{"id": "structures", "type": "info"}`. This is for compliance with JSON:API and their previous omission should be treated as a specification bug.
+- In cases where a server implementation treats filters on non-prefixed but unknown OPTIMADE fields as errors, implementations MUST update their known property list to handle new fields added to OPTIMADE in this version, such that they can continue to follow the expected behaviour for [Handling unknown property names](https://github.com/Materials-Consortia/OPTIMADE/blob/v1.2.0/optimade.rst#handling-unknown-property-names).
 
 
 ## v1.1.0 (July 8, 2021)

README.md

@@ -11,7 +11,8 @@ The Open Databases Integration for Materials Design (OPTIMADE) consortium aims t
 
 This repository contains the specification of the OPTIMADE API.
 
-* [optimade.rst](optimade.rst): The API specification.
+* [optimade.rst](optimade.rst): The API specification document.
+* [specification.optimade.org](https://specification.optimade.org): HTML builds of the different specification versions.
 * [schemas.optimade.org](https://schemas.optimade.org): Machine-readable schemas for property and server definitions.
 * [AUTHORS](AUTHORS): List of contributors.
 * [CHANGELOG](CHANGELOG.md): The release notes for each version of the specification.
@@ -46,9 +47,10 @@ Alternatively, the software using the file could itself be licensed in a way com
 
 ## How to cite
 
-If you use OPTIMADE to access or host data, we kindly ask that you cite our paper:
+If you use OPTIMADE to access or host data, we kindly ask that you cite our papers accompanying the version 1.0 and 1.2 releases:
 
 - Andersen *et al*, OPTIMADE, an API for exchanging materials data, *Sci. Data* **8**, 217 (2021) [10.1038/s41597-021-00974-z](https://doi.org/10.1038/s41597-021-00974-z)
+- Evans *et al*, Developments and applications of the OPTIMADE API for materials discovery, design, and data exchange, *arXiv preprint* (2024) [10.48550/arXiv.2402.00572](https://doi.org/10.48550/arXiv.2402.00572)
 
 To cite an individual version of the specification, please use the versioned records on Zenodo:
 

optimade.rst

@@ -1,6 +1,6 @@
-=========================================
-OPTIMADE API specification v1.2.0~develop
-=========================================
+======================================
+OPTIMADE API specification v1.2.0-rc.2
+======================================
 
 .. comment