diff --git a/schemas/resources/schemas/collection-draft/v1.0.0/ingest.md b/schemas/resources/schemas/collection-draft/v1.0.0/ingest.md new file mode 100644 index 0000000000..84bc5d573b --- /dev/null +++ b/schemas/resources/schemas/collection-draft/v1.0.0/ingest.md @@ -0,0 +1,85 @@ +## Collection Draft + +#### /providers/<provider-id>/collection-drafts/<native-id> + +### Create / Update a Collection Draft + +Collection Draft concepts can be created or updated by sending an HTTP PUT with the metadata to the URL `%CMR-ENDPOINT%/providers//collection-drafts/`. The response will include the [concept id](#concept-id) and the [revision id](#revision-id). The contents of the metadata is passed in the body of the request. + +``` + curl -XPOST \ + -H "Cmr-Pretty: true" \ + -H "Content-Type:application/vnd.nasa.cmr.umm+json" \ + -H "Authorization: Bearer XXXX" \ + "%CMR-ENDPOINT%/providers/PROV1/collection-drafts/sampleNativeId" \ + -d @sampleCollection.json +``` + +#### Successful Response in XML + +``` + + + CD1200000000-PROV1 + 1 + + + +``` +Subsequent ingests to the Collection Draft record will result in updates to it's metadata as well as increment the revision-id of the record. + +#### Successful Response in JSON + +By passing the option `-H "Accept: application/json"` to `curl`, one may +get a JSON response: + +``` + {"concept-id":"CD1200000000-PROV1","revision-id":1,"warnings":null,"existing-errors":null} +``` + +### Delete a Collection Draft + +Collection Draft metadata can be deleted by sending an HTTP DELETE to the URL `%CMR-ENDPOINT%/providers//collection-drafts/`. The response will include the [concept id](#concept-id) and the [revision id](#revision-id) of the tombstone. + +``` + curl -XDELETE \ + -H "Cmr-Pretty: true" \ + -H "Authorization: Bearer XXXX" \ + %CMR-ENDPOINT%/providers/PROV1/collection-drafts/sampleNative23Id" +``` + +#### Successful Response in XML + +``` + + + CD1200000000-PROV1 + 2 + +``` + +#### Successful Response in JSON + +``` + {"concept-id":"CD1200000000-PROV1","revision-id":2,"warnings":null,"existing-errors":null} +``` + +Attempting to delete an already deleted record will return +the following error message + +#### Unsuccessful Response in XML + +``` + + + Concept with native-id [sampleNative23Id] and concept-id [CD1200000000-PROV1] is already deleted. + +``` + +#### Unsuccessful Response in JSON + +``` + "errors": [ + "Concept with native-id [sampleNative23Id] and concept-id [CD1200000000-PROV1] is already deleted." + ] +``` diff --git a/schemas/resources/schemas/collection-draft/v1.0.0/search.md b/schemas/resources/schemas/collection-draft/v1.0.0/search.md new file mode 100644 index 0000000000..5d6c79789e --- /dev/null +++ b/schemas/resources/schemas/collection-draft/v1.0.0/search.md @@ -0,0 +1,184 @@ +### Collection Draft + +Collection Drafts are draft records that describe a data set. Collection metadata is stored in the JSON format [UMM-Collection Schema](https://git.earthdata.nasa.gov/projects/EMFD/repos/unified-metadata-model/browse/collection). + +#### Searching for Collection Drafts + +Collection Drafts can be searched for by sending a request to `%CMR-ENDPOINT%/collection-drafts`. XML reference, JSON and UMM JSON response formats are supported for Collection Draft searches. + +Collection Draft search results are paged. See [Paging Details](#paging-details) for more information on how to page through Collection Draft search results. + +##### Collection Draft Search Parameters + +The following parameters are supported when searching for Collection Drafts. + +##### Standard Parameters + +* page\_size +* page\_num +* pretty + +##### Collection Draft Matching Parameters + +These parameters will match fields within an Collection Draft. They are case insensitive by default. They support options specified. They also support searching with multiple values in the style of `name[]=key1&name[]=key2`. The values are bitwise `OR`ed together. + +* name - options: pattern, ignore\_case +* provider - options: pattern, ignore\_case +* native\_id - options: pattern, ignore\_case +* concept\_id + +``` + curl "%CMR-ENDPOINT%/collection-drafts?concept_id=CD1200000000-PROV1" +``` + +##### Collection Draft Search Response + +##### XML Reference + +The XML reference response format is used for returning references to search results. It consists of the following fields: + +| Field | Description | +| ---------- | -------------------------------------------------- | +| hits | the number of results matching the search query | +| took | time in milliseconds it took to perform the search | +| references | identifying information about each search result | + +The `references` field may contain multiple `reference` entries, each consisting of the following fields: + +| Field | Description | +| ----------- | ------------------------------------------------------------------ | +| name | the value of the Name field in Collection Draft metadata. | +| id | the CMR identifier for the result | +| location | the URL at which the full metadata for the result can be retrieved | +| revision-id | the internal CMR version number for the result | + +__Example__ + +``` + curl -H "Cmr-Pretty: true" \ + "%CMR-ENDPOINT%/collection-drafts.xml?name=collection-name" +``` + +__Sample response__ + +``` + + + 1 + 13 + + + collection-name + CD1200000000-PROV1 + %CMR-ENDPOINT%/concepts/CD1200000000-PROV1/4 + 4 + + + +``` + +##### JSON + +The JSON response includes the following fields. + +* hits - How many total records were found. +* took - How long the search took in milliseconds +* items - a list of the current page of records with the following fields + * concept\_id + * revision\_id + * provider\_id + * native\_id + * name + +__Example__ + +``` + curl -H "Cmr-Pretty: true" \ + "%CMR-ENDPOINT%/collection-drafts.json?name=collection-name" +``` + +__Sample response__ + +``` + { + "hits": 1, + "took": 10, + "items": [ + { + "concept_id": "CD1200000000-PROV1", + "revision\_id": 4, + "provider\_id": "PROV-1", + "native\_id": "sampleNative-Id", + "name": "collection-name" + } + ] + } +``` + +##### UMM JSON + +The UMM JSON response contains meta-metadata of the Collection Draft, the UMM fields and the associations field if applicable. [To search over specific versions of UMM](#umm-json). + +__Example__ + +``` + curl -H "pretty=true" \ + "%CMR-ENDPOINT%/collection-drafts.umm_json?name=collection-name" +``` + +__Sample response__ + +``` + { + "hits": 1, + "took": 17, + "items": [ + { + "meta": { + "revision-id": 1, + "deleted": false, + "provider-id": "PROV1", + "user-id": "exampleuser", + "native-id": "samplenativeid12", + "concept-id": "CD1200000000-PROV1", + "revision-date": "2022-10-26T19:17:27.021Z", + "concept-type": "collection-draft" + }, + "umm": { + "ShortName": "Mapping Short Name 1.17.0 CMR-8220", + "Version": "1", + "EntryTitle": "Mapping Example for UMM-C 1.17.0 CMR-8220", + "DOI": { + "DOI": "10.1234/DOIID", + "Authority": "https://doi.org/" + }, + ... + "MetadataSpecification": { + "URL": "https://cdn.earthdata.nasa.gov/umm/collection/v1.17.0", + "Name": "UMM-C", + "Version": "1.17.0" + } + } + } + ] + } +``` + +#### Sorting Collection Draft Results + +By default, Collection Draft results are sorted by name, then by provider-id. + +One or more sort keys can be specified using the sort_key[] parameter. The order used impacts searching. Fields can be prepended with a - to sort in descending order. Ascending order is the default but + (Note: + must be URL encoded as %2B) can be used to explicitly request ascending. + +##### Valid Collection Draft Sort Keys + +* name +* provider +* revision_date + +Examples of sorting by name in descending (reverse alphabetical) and ascending orders (Note: the `+` must be escaped with %2B): + +``` + curl "%CMR-ENDPOINT%/collection-drafts?sort_key\[\]=-name" + curl "%CMR-ENDPOINT%/collection-drafts?sort_key\[\]=%2Bname" +``` diff --git a/schemas/resources/schemas/data-quality-summary-draft/v1.0.0/ingest.md b/schemas/resources/schemas/data-quality-summary-draft/v1.0.0/ingest.md new file mode 100644 index 0000000000..331be37332 --- /dev/null +++ b/schemas/resources/schemas/data-quality-summary-draft/v1.0.0/ingest.md @@ -0,0 +1,85 @@ +## Data Quality Summary Draft + +#### /providers/<provider-id>/data-quality-summary-drafts/<native-id> + +### Create / Update a Data Quality Summary Draft + +Data Quality Summary Draft concepts can be created or updated by sending an HTTP PUT with the metadata to the URL `%CMR-ENDPOINT%/providers//data-quality-summary-drafts/`. The response will include the [concept id](#concept-id) and the [revision id](#revision-id). The contents of the metadata is passed in the body of the request. + +``` + curl -XPOST \ + -H "Cmr-Pretty: true" \ + -H "Content-Type:application/vnd.nasa.cmr.umm+json" \ + -H "Authorization: Bearer XXXX" \ + "%CMR-ENDPOINT%/providers/PROV1/data-quality-summary-drafts/sampleNativeId" \ + -d @sampleDataqualitysummary.json +``` + +#### Successful Response in XML + +``` + + + DQD1200000000-PROV1 + 1 + + + +``` +Subsequent ingests to the Data Quality Summary Draft record will result in updates to it's metadata as well as increment the revision-id of the record. + +#### Successful Response in JSON + +By passing the option `-H "Accept: application/json"` to `curl`, one may +get a JSON response: + +``` + {"concept-id":"DQD1200000000-PROV1","revision-id":1,"warnings":null,"existing-errors":null} +``` + +### Delete a Data Quality Summary Draft + +Data Quality Summary Draft metadata can be deleted by sending an HTTP DELETE to the URL `%CMR-ENDPOINT%/providers//data-quality-summary-drafts/`. The response will include the [concept id](#concept-id) and the [revision id](#revision-id) of the tombstone. + +``` + curl -XDELETE \ + -H "Cmr-Pretty: true" \ + -H "Authorization: Bearer XXXX" \ + %CMR-ENDPOINT%/providers/PROV1/data-quality-summary-drafts/sampleNative23Id" +``` + +#### Successful Response in XML + +``` + + + DQD1200000000-PROV1 + 2 + +``` + +#### Successful Response in JSON + +``` + {"concept-id":"DQD1200000000-PROV1","revision-id":2,"warnings":null,"existing-errors":null} +``` + +Attempting to delete an already deleted record will return +the following error message + +#### Unsuccessful Response in XML + +``` + + + Concept with native-id [sampleNative23Id] and concept-id [DQD1200000000-PROV1] is already deleted. + +``` + +#### Unsuccessful Response in JSON + +``` + "errors": [ + "Concept with native-id [sampleNative23Id] and concept-id [DQD1200000000-PROV1] is already deleted." + ] +``` diff --git a/schemas/resources/schemas/data-quality-summary-draft/v1.0.0/search.md b/schemas/resources/schemas/data-quality-summary-draft/v1.0.0/search.md new file mode 100644 index 0000000000..b2ca1f0124 --- /dev/null +++ b/schemas/resources/schemas/data-quality-summary-draft/v1.0.0/search.md @@ -0,0 +1,179 @@ +### Data Quality Summary Draft + +Data Quality Summary Drafts are draft records that inform users about the data quality of 1 or more collection(s) or dataset(s) and their granules. Data Quality Summary metadata is stored in the JSON format [UMM-Data-Quality-Summary Schema](https://git.earthdata.nasa.gov/projects/EMFD/repos/otherschemas/browse/data-quality-summary). + +#### Searching for Data Quality Summary Drafts + +Data Quality Summary Drafts can be searched for by sending a request to `%CMR-ENDPOINT%/data-quality-summary-drafts`. XML reference, JSON and UMM JSON response formats are supported for Data Quality Summary Draft searches. + +Data Quality Summary Draft search results are paged. See [Paging Details](#paging-details) for more information on how to page through Data Quality Summary Draft search results. + +##### Data Quality Summary Draft Search Parameters + +The following parameters are supported when searching for Data Quality Summary Drafts. + +##### Standard Parameters + +* page\_size +* page\_num +* pretty + +##### Data Quality Summary Draft Matching Parameters + +These parameters will match fields within a Data Quality Summary Draft. They are case insensitive by default. They support options specified. They also support searching with multiple values in the style of `name[]=key1&name[]=key2`. The values are bitwise `OR`ed together. + +* name - options: pattern, ignore\_case +* provider - options: pattern, ignore\_case +* native\_id - options: pattern, ignore\_case +* concept\_id + +``` + curl "%CMR-ENDPOINT%/data-quality-summary-drafts?concept_id=DQD1200000000-PROV1" +``` + +##### Data Quality Summary Draft Search Response + +##### XML Reference + +The XML reference response format is used for returning references to search results. It consists of the following fields: + +| Field | Description | +| ---------- | -------------------------------------------------- | +| hits | the number of results matching the search query | +| took | time in milliseconds it took to perform the search | +| references | identifying information about each search result | + +The `references` field may contain multiple `reference` entries, each consisting of the following fields: + +| Field | Description | +| ----------- | ------------------------------------------------------------------ | +| name | the value of the Name field in Data Quality Summary Draft metadata. | +| id | the CMR identifier for the result | +| location | the URL at which the full metadata for the result can be retrieved | +| revision-id | the internal CMR version number for the result | + +__Example__ + +``` + curl -H "Cmr-Pretty: true" \ + "%CMR-ENDPOINT%/data-quality-summary-drafts.xml?name=data-quality-summary-name-v1" +``` + +__Sample response__ + +``` + + + 1 + 13 + + + data-quality-summary-name-v1 + DQD1200000000-PROV1 + %CMR-ENDPOINT%/concepts/DQD1200000000-PROV1/4 + 4 + + + +``` + +##### JSON + +The JSON response includes the following fields. + +* hits - How many total Data Quality Summaries were found. +* took - How long the search took in milliseconds +* items - a list of the current page of Data Quality Summaries with the following fields + * concept\_id + * revision\_id + * provider\_id + * native\_id + * name + +__Example__ + +``` + curl -H "Cmr-Pretty: true" \ + "%CMR-ENDPOINT%/data-quality-summary-drafts.json?name=data-quality-summary-name-v1" +``` + +__Sample response__ + +``` + { + "hits": 1, + "took": 10, + "items": [ + { + "concept_id": "DQD1200000000-PROV1", + "revision\_id": 4, + "provider\_id": "PROV-1", + "native\_id": "sampleNative-Id", + "name": "data-quality-summary-name-v1" + } + ] + } +``` + +##### UMM JSON + +The UMM JSON response contains meta-metadata of the Data Quality Summary Draft, the UMM fields and the associations field if applicable. [To search over specific versions of UMM](#umm-json). + +__Example__ + +``` + curl -H "pretty=true" \ + "%CMR-ENDPOINT%/data-quality-summary-drafts.umm_json?name=data-quality-summary-name-v1" +``` + +__Sample response__ + +``` + { + "hits": 1, + "took": 17, + "items": [ + { + "meta": { + "revision-id": 1, + "deleted": false, + "provider-id": "PROV1", + "user-id": "exampleuser", + "native-id": "samplenativeid12", + "concept-id": "DQD1200000000-PROV1", + "revision-date": "2022-10-26T19:17:27.021Z", + "concept-type": "data-quality-summary-draft" + }, + "umm": { + "Id": "8EA5CA1F-E339-8065-26D7-53B64074D7CC", + "Name": "data-quality-summary-name-v1", + "Summary": "Summary", + "MetadataSpecification": { + "Name": "Data Quality Summary", + "Version": "1.0.0", + "URL": "https://cdn.earthdata.nasa.gov/generics/data-quality-summary/v1.0.0" + } + } + } + ] + } +``` + +#### Sorting Data Quality Summary Draft Results + +By default, Data Quality Summary Draft results are sorted by name, then by provider-id. + +One or more sort keys can be specified using the sort_key[] parameter. The order used impacts searching. Fields can be prepended with a - to sort in descending order. Ascending order is the default but + (Note: + must be URL encoded as %2B) can be used to explicitly request ascending. + +##### Valid Data Quality Summary Sort Keys + +* name +* provider +* revision_date + +Examples of sorting by name in descending (reverse alphabetical) and ascending orders (Note: the `+` must be escaped with %2B): + +``` + curl "%CMR-ENDPOINT%/data-quality-summary-drafts?sort_key\[\]=-name" + curl "%CMR-ENDPOINT%/data-quality-summary-drafts?sort_key\[\]=%2Bname" +``` diff --git a/schemas/resources/schemas/order-option-draft/v1.0.0/ingest.md b/schemas/resources/schemas/order-option-draft/v1.0.0/ingest.md new file mode 100644 index 0000000000..6f8cea2cbe --- /dev/null +++ b/schemas/resources/schemas/order-option-draft/v1.0.0/ingest.md @@ -0,0 +1,85 @@ +## Order Option Draft + +#### /providers/<provider-id>/order-option-drafts/<native-id> + +### Create / Update an Order Option Draft + +Order Option Draft concepts can be created or updated by sending an HTTP PUT with the metadata to the URL `%CMR-ENDPOINT%/providers//order-option-drafts/`. The response will include the [concept id](#concept-id) and the [revision id](#revision-id). The contents of the metadata is passed in the body of the request. + +``` + curl -XPOST \ + -H "Cmr-Pretty: true" \ + -H "Content-Type:application/vnd.nasa.cmr.umm+json" \ + -H "Authorization: Bearer XXXX" \ + "%CMR-ENDPOINT%/providers/PROV1/order-option-drafts/sampleNativeId" \ + -d @sampleOrderOption.json +``` + +#### Successful Response in XML + +``` + + + OOD1200000000-PROV1 + 1 + + + +``` +Subsequent ingests to the Order Option Draft record will result in updates to it's metadata as well as increment the revision-id of the record. + +#### Successful Response in JSON + +By passing the option `-H "Accept: application/json"` to `curl`, one may +get a JSON response: + +``` + {"concept-id":"OOD1200000000-PROV1","revision-id":1,"warnings":null,"existing-errors":null} +``` + +### Delete an Order Option Draft + +Order Option Draft metadata can be deleted by sending an HTTP DELETE to the URL `%CMR-ENDPOINT%/providers//order-option-drafts/`. The response will include the [concept id](#concept-id) and the [revision id](#revision-id) of the tombstone. + +``` + curl -XDELETE \ + -H "Cmr-Pretty: true" \ + -H "Authorization: Bearer XXXX" \ + %CMR-ENDPOINT%/providers/PROV1/order-option-drafts/sampleNative23Id" +``` + +#### Successful Response in XML + +``` + + + OOD1200000000-PROV1 + 2 + +``` + +#### Successful Response in JSON + +``` + {"concept-id":"OOD1200000000-PROV1","revision-id":2,"warnings":null,"existing-errors":null} +``` + +Attempting to delete an already deleted record will return +the following error message + +#### Unsuccessful Response in XML + +``` + + + Concept with native-id [sampleNative23Id] and concept-id [OOD1200000000-PROV1] is already deleted. + +``` + +#### Unsuccessful Response in JSON + +``` + "errors": [ + "Concept with native-id [sampleNative23Id] and concept-id [OOD1200000000-PROV1] is already deleted." + ] +``` diff --git a/schemas/resources/schemas/order-option-draft/v1.0.0/search.md b/schemas/resources/schemas/order-option-draft/v1.0.0/search.md new file mode 100644 index 0000000000..9860674042 --- /dev/null +++ b/schemas/resources/schemas/order-option-draft/v1.0.0/search.md @@ -0,0 +1,183 @@ +### Order Option Draft + +Order Option Drafts are draft records that inform users about the options that are available to a collection when ordering data files. Order Option metadata is stored in the JSON format [UMM-Order-Option Schema](https://git.earthdata.nasa.gov/projects/EMFD/repos/otherschemas/browse/order-option). + +#### Searching for Order Option Drafts + +Order Option Drafts can be searched for by sending a request to `%CMR-ENDPOINT%/order-option-drafts`. XML reference, JSON and UMM JSON response formats are supported for Order Option Draft searches. + +Order Option Draft search results are paged. See [Paging Details](#paging-details) for more information on how to page through Order Option Draft search results. + +##### Order Option Draft Search Parameters + +The following parameters are supported when searching for Order Option Drafts. + +##### Standard Parameters + +* page\_size +* page\_num +* pretty + +##### Order Option Draft Matching Parameters + +These parameters will match fields within an Order Option Draft. They are case insensitive by default. They support options specified. They also support searching with multiple values in the style of `name[]=key1&name[]=key2`. The values are bitwise `OR`ed together. + +* name - options: pattern, ignore\_case +* provider - options: pattern, ignore\_case +* native\_id - options: pattern, ignore\_case +* concept\_id + +``` + curl "%CMR-ENDPOINT%/order-option-drafts?concept_id=OOD1200000000-PROV1" +``` + +##### Order Option Draft Search Response + +##### XML Reference + +The XML reference response format is used for returning references to search results. It consists of the following fields: + +| Field | Description | +| ---------- | -------------------------------------------------- | +| hits | the number of results matching the search query | +| took | time in milliseconds it took to perform the search | +| references | identifying information about each search result | + +The `references` field may contain multiple `reference` entries, each consisting of the following fields: + +| Field | Description | +| ----------- | ------------------------------------------------------------------ | +| name | the value of the Name field in Order Option Draft metadata. | +| id | the CMR identifier for the result | +| location | the URL at which the full metadata for the result can be retrieved | +| revision-id | the internal CMR version number for the result | + +__Example__ + +``` + curl -H "Cmr-Pretty: true" \ + "%CMR-ENDPOINT%/order-option-drafts.xml?name=order-option-name" +``` + +__Sample response__ + +``` + + + 1 + 13 + + + order-option-name + OOD1200000000-PROV1 + %CMR-ENDPOINT%/concepts/OOD1200000000-PROV1/4 + 4 + + + +``` + +##### JSON + +The JSON response includes the following fields. + +* hits - How many total Order Options were found. +* took - How long the search took in milliseconds +* items - a list of the current page of Order Options with the following fields + * concept\_id + * revision\_id + * provider\_id + * native\_id + * name + +__Example__ + +``` + curl -H "Cmr-Pretty: true" \ + "%CMR-ENDPOINT%/order-option-drafts.json?name=order-option-name" +``` + +__Sample response__ + +``` + { + "hits": 1, + "took": 10, + "items": [ + { + "concept_id": "OOD1200000000-PROV1", + "revision\_id": 4, + "provider\_id": "PROV-1", + "native\_id": "sampleNative-Id", + "name": "order-option-name" + } + ] + } +``` + +##### UMM JSON + +The UMM JSON response contains meta-metadata of the Order Option Draft, the UMM fields and the associations field if applicable. [To search over specific versions of UMM](#umm-json). + +__Example__ + +``` + curl -H "pretty=true" \ + "%CMR-ENDPOINT%/order-option-drafts.umm_json?name=order-option-name" +``` + +__Sample response__ + +``` + { + "hits": 1, + "took": 17, + "items": [ + { + "meta": { + "revision-id": 1, + "deleted": false, + "provider-id": "PROV1", + "user-id": "exampleuser", + "native-id": "samplenativeid12", + "concept-id": "OOD1200000000-PROV1", + "revision-date": "2022-10-26T19:17:27.021Z", + "concept-type": "order-option-draft" + }, + "umm": { + "Id": "0AF0BB4E", + "Name": "With Browse", + "Description": "", + "Form": "
FtpPull FILEFORMAT true
", + "Scope":"PROVIDER", + "SortKey": "Name", + "Deprecated": false, + "MetadataSpecification": { + "Name": "Order Option", + "Version": "1.0.0", + "URL": "https://cdn.earthdata.nasa.gov/generics/order-option/v1.0.0" + } + } + } + ] + } +``` + +#### Sorting Order Option Draft Results + +By default, Order Option Draft results are sorted by name, then by provider-id. + +One or more sort keys can be specified using the sort_key[] parameter. The order used impacts searching. Fields can be prepended with a - to sort in descending order. Ascending order is the default but + (Note: + must be URL encoded as %2B) can be used to explicitly request ascending. + +##### Valid Order Option Sort Keys + +* name +* provider +* revision_date + +Examples of sorting by name in descending (reverse alphabetical) and ascending orders (Note: the `+` must be escaped with %2B): + +``` + curl "%CMR-ENDPOINT%/order-option-drafts?sort_key\[\]=-name" + curl "%CMR-ENDPOINT%/order-option-drafts?sort_key\[\]=%2Bname" +``` diff --git a/schemas/resources/schemas/service-draft/v1.0.0/ingest.md b/schemas/resources/schemas/service-draft/v1.0.0/ingest.md new file mode 100644 index 0000000000..e9cea3cfaf --- /dev/null +++ b/schemas/resources/schemas/service-draft/v1.0.0/ingest.md @@ -0,0 +1,85 @@ +## Service Draft + +#### /providers/<provider-id>/service-drafts/<native-id> + +### Create / Update a Service Draft + +Service Draft concepts can be created or updated by sending an HTTP PUT with the metadata to the URL `%CMR-ENDPOINT%/providers//service-drafts/`. The response will include the [concept id](#concept-id) and the [revision id](#revision-id). The contents of the metadata is passed in the body of the request. + +``` + curl -XPOST \ + -H "Cmr-Pretty: true" \ + -H "Content-Type:application/vnd.nasa.cmr.umm+json" \ + -H "Authorization: Bearer XXXX" \ + "%CMR-ENDPOINT%/providers/PROV1/service-drafts/sampleNativeId" \ + -d @sampleService.json +``` + +#### Successful Response in XML + +``` + + + SD1200000000-PROV1 + 1 + + + +``` +Subsequent ingests to the Service Draft record will result in updates to it's metadata as well as increment the revision-id of the record. + +#### Successful Response in JSON + +By passing the option `-H "Accept: application/json"` to `curl`, one may +get a JSON response: + +``` + {"concept-id":"SD1200000000-PROV1","revision-id":1,"warnings":null,"existing-errors":null} +``` + +### Delete a Service Draft + +Service Draft metadata can be deleted by sending an HTTP DELETE to the URL `%CMR-ENDPOINT%/providers//service-drafts/`. The response will include the [concept id](#concept-id) and the [revision id](#revision-id) of the tombstone. + +``` + curl -XDELETE \ + -H "Cmr-Pretty: true" \ + -H "Authorization: Bearer XXXX" \ + %CMR-ENDPOINT%/providers/PROV1/service-drafts/sampleNative23Id" +``` + +#### Successful Response in XML + +``` + + + SD1200000000-PROV1 + 2 + +``` + +#### Successful Response in JSON + +``` + {"concept-id":"SD1200000000-PROV1","revision-id":2,"warnings":null,"existing-errors":null} +``` + +Attempting to delete an already deleted record will return +the following error message + +#### Unsuccessful Response in XML + +``` + + + Concept with native-id [sampleNative23Id] and concept-id [SD1200000000-PROV1] is already deleted. + +``` + +#### Unsuccessful Response in JSON + +``` + "errors": [ + "Concept with native-id [sampleNative23Id] and concept-id [SD1200000000-PROV1] is already deleted." + ] +``` diff --git a/schemas/resources/schemas/service-draft/v1.0.0/search.md b/schemas/resources/schemas/service-draft/v1.0.0/search.md new file mode 100644 index 0000000000..fc97cb331e --- /dev/null +++ b/schemas/resources/schemas/service-draft/v1.0.0/search.md @@ -0,0 +1,187 @@ +### Service Draft + +Service Drafts are draft records that inform users about the services that are available to a collection when ordering data files. Service metadata is stored in the JSON format [UMM-Service Schema](https://git.earthdata.nasa.gov/projects/EMFD/repos/unified-metadata-model/browse/service). + +#### Searching for Service Drafts + +Service Drafts can be searched for by sending a request to `%CMR-ENDPOINT%/service-drafts`. XML reference, JSON and UMM JSON response formats are supported for Service Draft searches. + +Service Draft search results are paged. See [Paging Details](#paging-details) for more information on how to page through Service Draft search results. + +##### Service Draft Search Parameters + +The following parameters are supported when searching for Service Drafts. + +##### Standard Parameters + +* page\_size +* page\_num +* pretty + +##### Service Draft Matching Parameters + +These parameters will match fields within a Service Draft. They are case insensitive by default. They support options specified. They also support searching with multiple values in the style of `name[]=key1&name[]=key2`. The values are bitwise `OR`ed together. + +* name - options: pattern, ignore\_case +* provider - options: pattern, ignore\_case +* native\_id - options: pattern, ignore\_case +* concept\_id + +``` + curl "%CMR-ENDPOINT%/service-drafts?concept_id=SD1200000000-PROV1" +``` + +##### Service Draft Search Response + +##### XML Reference + +The XML reference response format is used for returning references to search results. It consists of the following fields: + +| Field | Description | +| ---------- | -------------------------------------------------- | +| hits | the number of results matching the search query | +| took | time in milliseconds it took to perform the search | +| references | identifying information about each search result | + +The `references` field may contain multiple `reference` entries, each consisting of the following fields: + +| Field | Description | +| ----------- | ------------------------------------------------------------------ | +| name | the value of the Name field in Service Draft metadata. | +| id | the CMR identifier for the result | +| location | the URL at which the full metadata for the result can be retrieved | +| revision-id | the internal CMR version number for the result | + +__Example__ + +``` + curl -H "Cmr-Pretty: true" \ + "%CMR-ENDPOINT%/service-drafts.xml?name=service-name" +``` + +__Sample response__ + +``` + + + 1 + 13 + + + service-name + SD1200000000-PROV1 + %CMR-ENDPOINT%/concepts/SD1200000000-PROV1/4 + 4 + + + +``` + +##### JSON + +The JSON response includes the following fields. + +* hits - How many total reecords were found. +* took - How long the search took in milliseconds +* items - a list of the current page of records with the following fields + * concept\_id + * revision\_id + * provider\_id + * native\_id + * name + +__Example__ + +``` + curl -H "Cmr-Pretty: true" \ + "%CMR-ENDPOINT%/service-drafts.json?name=service-name" +``` + +__Sample response__ + +``` + { + "hits": 1, + "took": 10, + "items": [ + { + "concept_id": "SD1200000000-PROV1", + "revision\_id": 4, + "provider\_id": "PROV-1", + "native\_id": "sampleNative-Id", + "name": "service-name" + } + ] + } +``` + +##### UMM JSON + +The UMM JSON response contains meta-metadata of the Service Draft, the UMM fields and the associations field if applicable. [To search over specific versions of UMM](#umm-json). + +__Example__ + +``` + curl -H "pretty=true" \ + "%CMR-ENDPOINT%/service-drafts.umm_json?name=service-name" +``` + +__Sample response__ + +``` + { + "hits": 1, + "took": 17, + "items": [ + { + "meta": { + "revision-id": 1, + "deleted": false, + "provider-id": "PROV1", + "user-id": "exampleuser", + "native-id": "samplenativeid12", + "concept-id": "SD1200000000-PROV1", + "revision-date": "2022-10-26T19:17:27.021Z", + "concept-type": "service-draft" + }, + "umm": { + "Name" : "Service-1.5.2", + "Aggregation": { + "Concatenate": { + "ConcatenateDefault": true + } + }, + "SupportedInputProjections" : [ { + "ProjectionName" : "Geographic", + "ProjectionAuthority" : "4326" + } ], + "MetadataSpecification" : { + "URL" : "https://cdn.earthdata.nasa.gov/umm/service/v1.5.2", + "Name" : "UMM-S", + "Version" : "1.5.2" + }, + "LongName" : "AIRS/Aqua L3 Daily Standard Physical Retrieval (AIRS+AMSU) 1 degree x 1 degree V006." + } + } + ] + } +``` + +#### Sorting Service Draft Results + +By default, Service Draft results are sorted by name, then by provider-id. + +One or more sort keys can be specified using the sort_key[] parameter. The order used impacts searching. Fields can be prepended with a - to sort in descending order. Ascending order is the default but + (Note: + must be URL encoded as %2B) can be used to explicitly request ascending. + +##### Valid Service Sort Keys + +* name +* provider +* revision_date + +Examples of sorting by name in descending (reverse alphabetical) and ascending orders (Note: the `+` must be escaped with %2B): + +``` + curl "%CMR-ENDPOINT%/service-drafts?sort_key\[\]=-name" + curl "%CMR-ENDPOINT%/service-drafts?sort_key\[\]=%2Bname" +``` diff --git a/schemas/resources/schemas/tool-draft/v1.0.0/ingest.md b/schemas/resources/schemas/tool-draft/v1.0.0/ingest.md new file mode 100644 index 0000000000..5cf002d6a9 --- /dev/null +++ b/schemas/resources/schemas/tool-draft/v1.0.0/ingest.md @@ -0,0 +1,85 @@ +## Tool Draft + +#### /providers/<provider-id>/tool-drafts/<native-id> + +### Create / Update a Tool Draft + +Tool Draft concepts can be created or updated by sending an HTTP PUT with the metadata to the URL `%CMR-ENDPOINT%/providers//tool-drafts/`. The response will include the [concept id](#concept-id) and the [revision id](#revision-id). The contents of the metadata is passed in the body of the request. + +``` + curl -XPOST \ + -H "Cmr-Pretty: true" \ + -H "Content-Type:application/vnd.nasa.cmr.umm+json" \ + -H "Authorization: Bearer XXXX" \ + "%CMR-ENDPOINT%/providers/PROV1/tool-drafts/sampleNativeId" \ + -d @sampleTool.json +``` + +#### Successful Response in XML + +``` + + + TD1200000000-PROV1 + 1 + + + +``` +Subsequent ingests to the Tool Draft record will result in updates to it's metadata as well as increment the revision-id of the record. + +#### Successful Response in JSON + +By passing the option `-H "Accept: application/json"` to `curl`, one may +get a JSON response: + +``` + {"concept-id":"TD1200000000-PROV1","revision-id":1,"warnings":null,"existing-errors":null} +``` + +### Delete a Tool Draft + +Tool Draft metadata can be deleted by sending an HTTP DELETE to the URL `%CMR-ENDPOINT%/providers//tool-drafts/`. The response will include the [concept id](#concept-id) and the [revision id](#revision-id) of the tombstone. + +``` + curl -XDELETE \ + -H "Cmr-Pretty: true" \ + -H "Authorization: Bearer XXXX" \ + %CMR-ENDPOINT%/providers/PROV1/tool-drafts/sampleNative23Id" +``` + +#### Successful Response in XML + +``` + + + TD1200000000-PROV1 + 2 + +``` + +#### Successful Response in JSON + +``` + {"concept-id":"TD1200000000-PROV1","revision-id":2,"warnings":null,"existing-errors":null} +``` + +Attempting to delete an already deleted record will return +the following error message + +#### Unsuccessful Response in XML + +``` + + + Concept with native-id [sampleNative23Id] and concept-id [TD1200000000-PROV1] is already deleted. + +``` + +#### Unsuccessful Response in JSON + +``` + "errors": [ + "Concept with native-id [sampleNative23Id] and concept-id [TD1200000000-PROV1] is already deleted." + ] +``` diff --git a/schemas/resources/schemas/tool-draft/v1.0.0/search.md b/schemas/resources/schemas/tool-draft/v1.0.0/search.md new file mode 100644 index 0000000000..0aa06b2fff --- /dev/null +++ b/schemas/resources/schemas/tool-draft/v1.0.0/search.md @@ -0,0 +1,197 @@ +### Tool Draft + +Tool Drafts are draft records that inform users about the tools that are available to a collection when working with data files. Tool metadata is stored in the JSON format [UMM-Service Schema](https://git.earthdata.nasa.gov/projects/EMFD/repos/unified-metadata-model/browse/tool). + +#### Searching for Tool Drafts + +Tool Drafts can be searched for by sending a request to `%CMR-ENDPOINT%/tool-drafts`. XML reference, JSON and UMM JSON response formats are supported for Tool Draft searches. + +Tool Draft search results are paged. See [Paging Details](#paging-details) for more information on how to page through Tool Draft search results. + +##### Tool Draft Search Parameters + +The following parameters are supported when searching for Tool Drafts. + +##### Standard Parameters + +* page\_size +* page\_num +* pretty + +##### Tool Draft Matching Parameters + +These parameters will match fields within a Tool Draft. They are case insensitive by default. They support options specified. They also support searching with multiple values in the style of `name[]=key1&name[]=key2`. The values are bitwise `OR`ed together. + +* name - options: pattern, ignore\_case +* provider - options: pattern, ignore\_case +* native\_id - options: pattern, ignore\_case +* concept\_id + +``` + curl "%CMR-ENDPOINT%/tool-drafts?concept_id=TD1200000000-PROV1" +``` + +##### Tool Draft Search Response + +##### XML Reference + +The XML reference response format is used for returning references to search results. It consists of the following fields: + +| Field | Description | +| ---------- | -------------------------------------------------- | +| hits | the number of results matching the search query | +| took | time in milliseconds it took to perform the search | +| references | identifying information about each search result | + +The `references` field may contain multiple `reference` entries, each consisting of the following fields: + +| Field | Description | +| ----------- | ------------------------------------------------------------------ | +| name | the value of the Name field in Service Draft metadata. | +| id | the CMR identifier for the result | +| location | the URL at which the full metadata for the result can be retrieved | +| revision-id | the internal CMR version number for the result | + +__Example__ + +``` + curl -H "Cmr-Pretty: true" \ + "%CMR-ENDPOINT%/tool-drafts.xml?name=tool-name" +``` + +__Sample response__ + +``` + + + 1 + 13 + + + tool-name + TD1200000000-PROV1 + %CMR-ENDPOINT%/concepts/TD1200000000-PROV1/4 + 4 + + + +``` + +##### JSON + +The JSON response includes the following fields. + +* hits - How many total records were found. +* took - How long the search took in milliseconds +* items - a list of the current page of records with the following fields + * concept\_id + * revision\_id + * provider\_id + * native\_id + * name + +__Example__ + +``` + curl -H "Cmr-Pretty: true" \ + "%CMR-ENDPOINT%/tool-drafts.json?name=tool-name" +``` + +__Sample response__ + +``` + { + "hits": 1, + "took": 10, + "items": [ + { + "concept_id": "TD1200000000-PROV1", + "revision\_id": 4, + "provider\_id": "PROV-1", + "native\_id": "sampleNative-Id", + "name": "tool-name" + } + ] + } +``` + +##### UMM JSON + +The UMM JSON response contains meta-metadata of the Tool Draft, the UMM fields and the associations field if applicable. [To search over specific versions of UMM](#umm-json). + +__Example__ + +``` + curl -H "pretty=true" \ + "%CMR-ENDPOINT%/tool-drafts.umm_json?name=tool-name" +``` + +__Sample response__ + +``` + { + "hits": 1, + "took": 17, + "items": [ + { + "meta": { + "revision-id": 1, + "deleted": false, + "provider-id": "PROV1", + "user-id": "exampleuser", + "native-id": "samplenativeid12", + "concept-id": "TD1200000000-PROV1", + "revision-date": "2022-10-26T19:17:27.021Z", + "concept-type": "tool-draft" + }, + "umm": { + "Type": "Web User Interface" + "Description": "SOTO ... research.", + "Version": "2", + "Name": "SOTO", + "LongName": "State Of The Ocean", + "PotentialAction": { + "Type": "SearchAction", + "Target": { + "Type": "EntryPoint", + "ResponseContentType": ["text/html"], + "UrlTemplate": "https://podaac-tools.jpl.nasa.gov/soto/#b=BlueMarble_ShadedRelief_Bathymetry&l={+layers}&ve={+bbox}&d={+date}", + "Description": "SOTO is a suite of tools ... related research.", + "HttpMethod": ["GET"] + }, + "QueryInput": [{ + "ValueName": "bbox", + "Description": "A spatial bounding box ...space character.", + "ValueRequired": false, + "ValueType": "https://schema.org/box" + }] + }, + "MetadataSpecification": { + "URL": "https://cdn.earthdata.nasa.gov/umm/tool/v1.2.0", + "Name": "UMM-T", + "Version": "1.2.0" + } + } + } + ] + } +``` + +#### Sorting Tool Draft Results + +By default, Tool Draft results are sorted by name, then by provider-id. + +One or more sort keys can be specified using the sort_key[] parameter. The order used impacts searching. Fields can be prepended with a - to sort in descending order. Ascending order is the default but + (Note: + must be URL encoded as %2B) can be used to explicitly request ascending. + +##### Valid Tool Sort Keys + +* name +* provider +* revision_date + +Examples of sorting by name in descending (reverse alphabetical) and ascending orders (Note: the `+` must be escaped with %2B): + +``` + curl "%CMR-ENDPOINT%/tool-drafts?sort_key\[\]=-name" + curl "%CMR-ENDPOINT%/tool-drafts?sort_key\[\]=%2Bname" +``` diff --git a/schemas/resources/schemas/variable-draft/v1.0.0/ingest.md b/schemas/resources/schemas/variable-draft/v1.0.0/ingest.md new file mode 100644 index 0000000000..8783dc01fc --- /dev/null +++ b/schemas/resources/schemas/variable-draft/v1.0.0/ingest.md @@ -0,0 +1,85 @@ +## Variable Draft + +#### /providers/<provider-id>/variable-drafts/<native-id> + +### Create / Update a Variable Draft + +Variable Draft concepts can be created or updated by sending an HTTP PUT with the metadata to the URL `%CMR-ENDPOINT%/providers//variable-drafts/`. The response will include the [concept id](#concept-id) and the [revision id](#revision-id). The contents of the metadata is passed in the body of the request. + +``` + curl -XPOST \ + -H "Cmr-Pretty: true" \ + -H "Content-Type:application/vnd.nasa.cmr.umm+json" \ + -H "Authorization: Bearer XXXX" \ + "%CMR-ENDPOINT%/providers/PROV1/variable-drafts/sampleNativeId" \ + -d @sampleVariable.json +``` + +#### Successful Response in XML + +``` + + + VD1200000000-PROV1 + 1 + + + +``` +Subsequent ingests to the Variable Draft record will result in updates to it's metadata as well as increment the revision-id of the record. + +#### Successful Response in JSON + +By passing the option `-H "Accept: application/json"` to `curl`, one may +get a JSON response: + +``` + {"concept-id":"VD1200000000-PROV1","revision-id":1,"warnings":null,"existing-errors":null} +``` + +### Delete a Variable Draft + +Variable Draft metadata can be deleted by sending an HTTP DELETE to the URL `%CMR-ENDPOINT%/providers//variable-drafts/`. The response will include the [concept id](#concept-id) and the [revision id](#revision-id) of the tombstone. + +``` + curl -XDELETE \ + -H "Cmr-Pretty: true" \ + -H "Authorization: Bearer XXXX" \ + %CMR-ENDPOINT%/providers/PROV1/variable-drafts/sampleNative23Id" +``` + +#### Successful Response in XML + +``` + + + VD1200000000-PROV1 + 2 + +``` + +#### Successful Response in JSON + +``` + {"concept-id":"VD1200000000-PROV1","revision-id":2,"warnings":null,"existing-errors":null} +``` + +Attempting to delete an already deleted record will return +the following error message + +#### Unsuccessful Response in XML + +``` + + + Concept with native-id [sampleNative23Id] and concept-id [VD1200000000-PROV1] is already deleted. + +``` + +#### Unsuccessful Response in JSON + +``` + "errors": [ + "Concept with native-id [sampleNative23Id] and concept-id [VD1200000000-PROV1] is already deleted." + ] +``` diff --git a/schemas/resources/schemas/variable-draft/v1.0.0/search.md b/schemas/resources/schemas/variable-draft/v1.0.0/search.md new file mode 100644 index 0000000000..412f703ac5 --- /dev/null +++ b/schemas/resources/schemas/variable-draft/v1.0.0/search.md @@ -0,0 +1,196 @@ +### Variable Draft + +Variable Drafts are draft records that inform users about the variables that are available in a collection when working with data files. Variable metadata is stored in the JSON format [UMM-Service Schema](https://git.earthdata.nasa.gov/projects/EMFD/repos/unified-metadata-model/browse/variable). + +#### Searching for Variable Drafts + +Variable Drafts can be searched for by sending a request to `%CMR-ENDPOINT%/variable-drafts`. XML reference, JSON and UMM JSON response formats are supported for Variable Draft searches. + +Variable Draft search results are paged. See [Paging Details](#paging-details) for more information on how to page through Variable Draft search results. + +##### Variable Draft Search Parameters + +The following parameters are supported when searching for Variable Drafts. + +##### Standard Parameters + +* page\_size +* page\_num +* pretty + +##### Variable Draft Matching Parameters + +These parameters will match fields within a Variable Draft. They are case insensitive by default. They support options specified. They also support searching with multiple values in the style of `name[]=key1&name[]=key2`. The values are bitwise `OR`ed together. + +* name - options: pattern, ignore\_case +* provider - options: pattern, ignore\_case +* native\_id - options: pattern, ignore\_case +* concept\_id + +``` + curl "%CMR-ENDPOINT%/variable-drafts?concept_id=VD1200000000-PROV1" +``` + +##### Variable Draft Search Response + +##### XML Reference + +The XML reference response format is used for returning references to search results. It consists of the following fields: + +| Field | Description | +| ---------- | -------------------------------------------------- | +| hits | the number of results matching the search query | +| took | time in milliseconds it took to perform the search | +| references | identifying information about each search result | + +The `references` field may contain multiple `reference` entries, each consisting of the following fields: + +| Field | Description | +| ----------- | ------------------------------------------------------------------ | +| name | the value of the Name field in Service Draft metadata. | +| id | the CMR identifier for the result | +| location | the URL at which the full metadata for the result can be retrieved | +| revision-id | the internal CMR version number for the result | + +__Example__ + +``` + curl -H "Cmr-Pretty: true" \ + "%CMR-ENDPOINT%/variable-drafts.xml?name=variable-name" +``` + +__Sample response__ + +``` + + + 1 + 13 + + + variable-name + VD1200000000-PROV1 + %CMR-ENDPOINT%/concepts/VD1200000000-PROV1/4 + 4 + + + +``` + +##### JSON + +The JSON response includes the following fields. + +* hits - How many total records were found. +* took - How long the search took in milliseconds +* items - a list of the current page of records with the following fields + * concept\_id + * revision\_id + * provider\_id + * native\_id + * name + +__Example__ + +``` + curl -H "Cmr-Pretty: true" \ + "%CMR-ENDPOINT%/variable-drafts.json?name=variable-name" +``` + +__Sample response__ + +``` + { + "hits": 1, + "took": 10, + "items": [ + { + "concept_id": "VD1200000000-PROV1", + "revision\_id": 4, + "provider\_id": "PROV-1", + "native\_id": "sampleNative-Id", + "name": "variable-name" + } + ] + } +``` + +##### UMM JSON + +The UMM JSON response contains meta-metadata of the Variable Draft, the UMM fields and the associations field if applicable. [To search over specific versions of UMM](#umm-json). + +__Example__ + +``` + curl -H "pretty=true" \ + "%CMR-ENDPOINT%/variable-drafts.umm_json?name=variable-name" +``` + +__Sample response__ + +``` + { + "hits": 1, + "took": 17, + "items": [ + { + "meta": { + "revision-id": 1, + "deleted": false, + "provider-id": "PROV1", + "user-id": "exampleuser", + "native-id": "samplenativeid12", + "concept-id": "VD1200000000-PROV1", + "revision-date": "2022-10-26T19:17:27.021Z", + "concept-type": "variable-draft" + }, + "umm": { + "VariableType" : "SCIENCE_VARIABLE", + "DataType" : "float32", + "Offset" : 0, + "Scale" : 1, + "Sets" : [ { + "Name" : "data", + "Type" : "data", + "Size" : 4, + "Index" : 4 + }], + "Dimensions" : [ { + "Name" : "latitude", + "Size" : 2166, + "Type" : "LATITUDE_DIMENSION" + }, { + "Name" : "longitude", + "Size" : 4061, + "Type" : "LONGITUDE_DIMENSION" + }], + "Definition" : "2D Amplitude of IFG", + "Name" : "science/grids/data/amplitude", + "AcquisitionSourceName" : "SENTINEL-1 C-SAR", + "ValidRanges" : [{"Min" : 0}], + "Units" : "watt", + "LongName" : "Amplitude" + } + } + ] + } +``` + +#### Sorting Variable Draft Results + +By default, Variable Draft results are sorted by name, then by provider-id. + +One or more sort keys can be specified using the sort_key[] parameter. The order used impacts searching. Fields can be prepended with a - to sort in descending order. Ascending order is the default but + (Note: + must be URL encoded as %2B) can be used to explicitly request ascending. + +##### Valid Variable Sort Keys + +* name +* provider +* revision_date + +Examples of sorting by name in descending (reverse alphabetical) and ascending orders (Note: the `+` must be escaped with %2B): + +``` + curl "%CMR-ENDPOINT%/variable-drafts?sort_key\[\]=-name" + curl "%CMR-ENDPOINT%/variable-drafts?sort_key\[\]=%2Bname" +```