Release v1.5.0 of the API

v2_1/ws/rest/docs/4_3_structural_queries.md

@@ -26,6 +26,12 @@ The following resources are defined:
 - actualconstraint (a type of contentconstraint stating what data are actually present)
 - allowedconstraint (a type of contentconstraint defining what data are allowed)
 - attachmentconstraint
+- transformationscheme
+- rulesetscheme
+- userdefinedoperatorscheme
+- customtypescheme
+- namepersonalisationscheme
+- vtlmappingscheme
 - structure (This type can be used to retrieve any type of structural metadata matching the supplied parameters)
 
 
@@ -77,6 +83,12 @@ SDMX uses the *item scheme* pattern to model SDMX collections of items. These ar
 - dataconsumerscheme
 - organisationunitscheme
 - reportingtaxonomy
+- transformationscheme
+- rulesetscheme
+- userdefinedoperatorscheme
+- customtypescheme
+- namepersonalisationscheme
+- vtlmappingscheme
 
 Although it is not following the *item scheme* pattern, *hierarchicalcodelist* is also a collection, i.e. a collection of hierarchies.
 
@@ -109,7 +121,7 @@ The following parameters are used to further describe the desired results, once
 
 Parameter | Type | Description | Default
 --- | --- | --- | ---
-detail | *String* | This attribute specifies the desired amount of information to be returned. For example, it is possible to instruct the web service to return only basic information about the maintainable artefact (i.e.: id, agency id, version and name). Most notably, items of item schemes will not be returned (for example, it will not return the codes in a code list query). Possible values are: `allstubs` (all artefacts should be returned as stubs, containing only identification information, as well as the artefacts' name), `referencestubs` (referenced artefacts should be returned as stubs, containing only identification information, as well as the artefacts' name), `referencepartial` (referenced item schemes should only include items used by the artefact to be returned. For example, a concept scheme would only contain the concepts used in a DSD, and its `isPartial` flag would be set to `true`), `allcompletestubs` (all artefacts should be returned as complete stubs, containing identification information, the artefacts' name, description, annotations and isFinal information), `referencecompletestubs` (referenced artefacts should be returned as complete stubs, containing identification information, the artefacts' name, description, annotations and isFinal information) and `full` (all available information for all artefacts should be returned). | **full**
+detail | *String* | This attribute specifies the desired amount of information to be returned. For example, it is possible to instruct the web service to return only basic information about the maintainable artefact (i.e.: id, agency id, version and name). Most notably, items of item schemes will not be returned (for example, it will not return the codes in a code list query). Possible values are: `allstubs` (all artefacts should be returned as stubs, containing only identification information, as well as the artefacts' name), `referencestubs` (referenced artefacts should be returned as stubs, containing only identification information, as well as the artefacts' name), `referencepartial` (referenced item schemes should only include items used by the artefact to be returned. For example, a concept scheme would only contain the concepts used in a DSD, and its `isPartial` flag would be set to `true`. Likewise, if a dataflow has been constrained, then the codelists referenced by the DSD referenced by the dataflow should only contain the codes allowed by the content constraint), `allcompletestubs` (all artefacts should be returned as complete stubs, containing identification information, the artefacts' name, description, annotations and isFinal information), `referencecompletestubs` (referenced artefacts should be returned as complete stubs, containing identification information, the artefacts' name, description, annotations and isFinal information) and `full` (all available information for all artefacts should be returned). | **full**
 references | *String* | This attribute instructs the web service to return (or not) the artefacts referenced by the artefact to be returned (for example, the code lists and concepts used by the data structure definition matching the query), as well as the artefacts that use the matching artefact (for example, the dataflows that use the data structure definition matching the query). Possible values are: `none` (no references will be returned), `parents` (the artefacts that use the artefact matching the query), `parentsandsiblings` (the artefacts that use the artefact matching the query, as well as the artefacts referenced by these artefacts), `children` (artefacts referenced by the artefact to be returned), `descendants` (references of references, up to any level, will also be returned), `all` (the combination of parentsandsiblings and descendants). In addition, a `concrete type of resource` may also be used (for example, references=codelist). | **none**
 
 #### Applicability and meaning of references attribute
@@ -121,11 +133,11 @@ Maintainable artefact | Artefacts returned
 AgencyScheme | *Categorisation*, *Process*, *MetadataStructureDefinition*, *StructureSet*
 Categorisation | All
 CategoryScheme | *Categorisations*, *Process*, *StructureSet*
-Codelist | *Categorisation*, *Process*, *HierarchicalCodelist*, *ConceptScheme*, *DataStructureDefinition*, *MetadataStructureDefinition*, *StructureSet*
-ConceptScheme | *Categorisation*, *Process*, Codelist, *DataStructureDefinition*, *MetadataStructureDefinition*, *StructureSet*
+Codelist | *Categorisation*, *Process*, *HierarchicalCodelist*, *ConceptScheme*, *DataStructureDefinition*, *MetadataStructureDefinition*, *StructureSet*, *VtlMappingScheme*
+ConceptScheme | *Categorisation*, *Process*, Codelist, *DataStructureDefinition*, *MetadataStructureDefinition*, *StructureSet*, *VtlMappingScheme*
 Constraint | *Categorisation*, *Process*, DataProviderScheme, DataStructureDefinition, Dataflow, MetadataStructureDefinition, Metadataflow, ProvisionAgreement
 DataConsumerScheme | *Categorisation*, *Process*, *MetadataStructureDefinition*, *StructureSet*
-Dataflow | *Categorisation*, *Process*, *Constraint*, DataStructureDefinition, *ProvisionAgreement*, *ReportingTaxonomy*, *StructureSet*
+Dataflow | *Categorisation*, *Process*, *Constraint*, DataStructureDefinition, *ProvisionAgreement*, *ReportingTaxonomy*, *StructureSet*, *VtlMappingScheme*
 DataProviderScheme | *Categorisation*, *Process*, *Constraint*, *ProvisionAgreement*, *MetadataStructureDefinition*, *StructureSet*
 DataStructureDefinition | *Categorisation*, *Process*, Codelist, ConceptScheme, *Constraint*, *Dataflow*, *StructureSet*
 HierarchicalCodelist | *Categorisation*, *Process*, Codelist, *StructureSet*
@@ -136,6 +148,12 @@ Process | All
 ProvisionAgreement | *Categorisation*, *Process*, DataProviderScheme, Dataflow, Metadataflow, *Constraint*
 ReportingTaxonomy | *Categorisation*, *Process*, Dataflow, Metadataflow, *StructureSet*
 StructureSet | *Categorisation*, *Process*, DataStructureDefinition, MetadataStructureDefinition, CategoryScheme, DataProviderScheme, DataConsumerScheme, AgencyScheme, OrganisationUnitScheme, ConceptScheme, Codelist, ReportingTaxonomy, HierarchicalCodelist, Dataflow, Metadataflow
+CustomTypeScheme | AgencyScheme, _Categorisation_, _TranformationScheme_
+NamePersonalisationScheme | AgencyScheme, _Categorisation_, _TranformationScheme_
+RulesetScheme | AgencyScheme, _Categorisation_, _TranformationScheme_, VtlMappingScheme
+TranformationScheme | AgencyScheme, _Categorisation_, CustomTypeScheme, NamePersonalisationScheme, RulesetScheme, UserDefinedOperatorScheme, VtlMappingScheme
+UserDefinedOperatorScheme | AgencyScheme, _Categorisation_, _TranformationScheme_, VtlMappingScheme
+VtlMappingScheme | AgencyScheme, _Categorisation_, Codelist, ConceptScheme, Dataflow, _RulesetScheme_, _TranformationScheme_, _UserDefinedOperatorScheme_
 
 ### Examples
 

v2_1/ws/rest/docs/4_5_schema_queries.md

@@ -7,8 +7,9 @@ The following resource is defined:
 
 - schema
 
-This resource allows a client to ask a service to return an XML schema, which defines data (or reference metadata) validity within a certain context. The service must take into account the constraints that apply within that context (DSD or MSD, dataflow or metadataflow, or provision agreement).
+This resource allows a client to ask a service to return a schema, i.e. a document which defines data validity within a certain context. The service must take into account the constraints that apply within that context (DSD or MSD, dataflow or metadataflow, or provision agreement).
 
+This is typically used for validation purposes but it may also be used for communication purposes, i.e. as a way to inform providers about the data they are expected to report.
 
 ### Parameters
 
@@ -48,6 +49,14 @@ Parameter | Type | Description
 dimensionAtObservation | A string compliant with the SDMX *common:NCNameIDType* | The ID of the dimension to be attached at the observation level.
 explicitMeasure | *Boolean* | For cross-sectional data validation, indicates whether observations are strongly typed (defaults to `false`).
 
+### Using an SDMX format for the response
+
+By default, a *schema* query will return an XML schema (i.e. an `xsd` file). However, it is also possible to get the response in one of the SDMX Structure formats. In that case, the response should only include the following types of artefact: data structures, codelists, concept schemes and agency schemes. The various item schemes must only contain the following:
+
+- For codelists, the codes that are allowed after applying the constraints up to the specified *context*;
+- For concept schemes, the concepts that are used by the data structure;
+- For agency schemes, the agencies maintaining artefacts that are part of the response.
+
 ### Examples
 
 * To retrieve the schema for data supplied within the context of version 1.0 of the provision agreement EXR_WEB maintained by the ECB:

v2_1/ws/rest/docs/4_6_conneg.md

@@ -20,23 +20,43 @@ A few examples are listed below
 
 In case the client does not specify the desired format and version of the response message, or only specifies the generic application/xml format, the SDMX RESTful web service should return:
 
-- The most recent version, that the service supports, of the SDMX-ML Structure format for structural metadata queries;
-- The most recent version, that the service supports, of the SDMX-ML Generic Data format for data queries;
-- The most recent version, that the service supports, of the SDMX-ML Generic Metadata format for metadata queries.
-
-The list below indicates the valid formats for SDMX RESTful web services, compliant with version 2.1 of the SDMX standard:
-
-    application/vnd.sdmx.genericdata+xml;version=2.1
-    application/vnd.sdmx.structurespecificdata+xml;version=2.1
-    application/vnd.sdmx.generictimeseriesdata+xml;version=2.1
-    application/vnd.sdmx.structurespecifictimeseriesdata+xml;version=2.1
-    application/vnd.sdmx.data+json;version=1.0.0
-    application/vnd.sdmx.data+csv;version=1.0.0
-    application/vnd.sdmx.genericmetadata+xml;version=2.1
-    application/vnd.sdmx.structurespecificmetadata+xml;version=2.1
-    application/vnd.sdmx.structure+xml;version=2.1
-    application/vnd.sdmx.structure+json;version=1.0.0
-    application/vnd.sdmx.schema+xml;version=2.1
+- The most recent version, that the service supports, of the SDMX-ML Structure format for **structural metadata** queries;
+- The most recent version, that the service supports, of the SDMX-ML Generic Data format for **data** queries;
+- The most recent version, that the service supports, of the SDMX-ML Generic Metadata format for **reference metadata** queries;
+- An XML schema (i.e. an `xsd` file) for **schema** queries.
+- The most recent version, that the service supports, of the SDMX-ML Structure format for **data availability** queries;
+
+The list below indicates the valid formats for SDMX RESTful web services, compliant with version 2.1 of the SDMX standard, organized by type of queries. The default media type is highlighted in bold.
+
+#### Structural metadata queries
+
+- **application/vnd.sdmx.structure+xml;version=2.1**
+- application/vnd.sdmx.structure+json;version=1.0.0
+
+#### Data queries
+
+- **application/vnd.sdmx.genericdata+xml;version=2.1**
+- application/vnd.sdmx.structurespecificdata+xml;version=2.1
+- application/vnd.sdmx.generictimeseriesdata+xml;version=2.1
+- application/vnd.sdmx.structurespecifictimeseriesdata+xml;version=2.1
+- application/vnd.sdmx.data+json;version=1.0.0
+- application/vnd.sdmx.data+csv;version=1.0.0;labels=[*id*|both];timeFormat=[*original*|normalized]
+
+#### Reference metadata queries    
+
+- **application/vnd.sdmx.genericmetadata+xml;version=2.1**
+- application/vnd.sdmx.structurespecificmetadata+xml;version=2.1
+
+#### Schema queries    
+
+- **application/vnd.sdmx.schema+xml;version=2.1**
+- application/vnd.sdmx.structure+xml;version=2.1
+- application/vnd.sdmx.structure+json;version=1.0.0
+
+#### Data availability queries
+
+- **application/vnd.sdmx.structure+xml;version=2.1**
+- application/vnd.sdmx.structure+json;version=1.0.0
 
 ### Selection of the Appropriate language
 
@@ -55,3 +75,7 @@ Compression could be enabled using the appropriate [Accept-Encoding header](http
 The [Vary header](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) is used to indicate the list of headers that are relevant for a particular service.
 
 For example, services that offer data in multiple formats will rely on the HTTP Accept header, but this header will likely be irrelevant for services that support only one format. Using the `Vary` header to indicate which headers are effectively used by the server helps web caches and Content Delivery Networks to build appropriate cache keys.
+
+### A note about SDMX-CSV
+
+SDMX-CSV offers the possibility to set the value for two parameters via the media-type. These parameters are `label` and `timeFormat`; both are optional. The default values for these parameters are marked with * in the above media-type (i.e. `id` and `original` respectively). For additional information about these parameters, please refer to the [SDMX-CSV specification](https://sdmx.org/?sdmx_news=sdmx-csv-format-specifications-just-released).