Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions core/openapi/parameters/profile.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
---
name: profile
in: query
description:
One or more identifiers that provide information about additional
semantics (constraints, conventions, extensions), in addition to
those defined by the media type, that are associated with the
target resource.
required: false
schema:
type: array
items:
type: string
explode: false
style: form
8 changes: 8 additions & 0 deletions core/openapi/schemas/linkBase.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,14 @@ properties:
identifier.
length:
type: integer
profile:
type: array
items: string
description:
One or more identifiers that provide information about additional
semantics (constraints, conventions, extensions), in addition to
those defined by the media type, that are associated with the
target resource.
created:
type: string
description:
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
[[ats_query-param-profile]]
[conformance_class]
====
[%metadata]
identifier:: http://www.opengis.net/spec/ogcapi-records-1/1.0/conf/query-param-profile
target:: http://www.opengis.net/spec/ogcapi-records-1/1.0/req/query-param-profile
classification:: Target Type:Web API
abstract-test:: /conf/query-param-profile/definition
abstract-test:: /conf/query-param-profile/response
====

==== Query Parameter Profile

include::query-param-profile/ATS_definition.adoc[]

include::query-param-profile/ATS_response.adoc[]
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
[[ats_query-param-profile_definition]]
[abstract_test]
====
[%metadata]
identifier:: /conf/query-param-profile/definition
target:: /req/query-param-profile/definition
test-purpose:: Validate `profile` query parameter.
test-method::
+
--
. Construct a path for a searchable endpoint and include the `profile` query parameter.
. Validate that the `profile` query parameter is constructed correctly using an OpenAPI Specification 3.0 fragment:

[source,YAML]
----
name: profile
in: query
required: false
schema:
type: array
items:
type: string
explode: false
style: form
----
. Issue an HTTP GET request on that path.
. Check that the value of the returned HTTP status header is +200+.
--
====
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
[[ats_query-param-profile_response]]
[abstract_test]
====
[%metadata]
identifier:: /conf/query-param-profile/response
target:: /req/query-param-profile/response
test-purpose:: Validate `profile` query parameter.
test-method::
+
--
. Construct a path for a searchable endpoint as per test <<ats_query-param-profile_definition,/conf/query-param-profile/definition>>.
. Issue an HTTP GET request on that path.
. Check that the value of the returned HTTP status header is +200+.
. Check that that the content of response adheres to the requirements of the specified profile(s).
--
====
2 changes: 2 additions & 0 deletions core/standard/annex_ats.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ include::abstract_tests/building-blocks/ATS_class_records-api.adoc[]

include::abstract_tests/building-blocks/ATS_class_record-core-query-parameters.adoc[]

include::abstract_tests/building-blocks/ATS_class_query-param-profile.adoc[]

include::abstract_tests/building-blocks/ATS_class_record-filter.adoc[]

include::abstract_tests/building-blocks/ATS_class_sorting.adoc[]
Expand Down
32 changes: 32 additions & 0 deletions core/standard/clause_10_profile.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
[[profile-parameter]]
== Requirements Class "Profile query parameter"

The Requirements Class "Profile query parameter" specifies additional provisions for properties that reference another resource.

include::requirements/building-blocks/requirements_class_query-param-profile.adoc[]

Some properties may be represented in multiple representations in the same format, depending on the intended use of the data. One example are references to another web resource (see the <<rc_profile-references>>).

<<rfc6906,RFC 6906 The 'profile' Link Relation Type>> defines the concept of a profile to support such use cases.

A profile is defined not to alter the semantics of the resource representation itself, but to allow clients to learn about additional semantics (constraints, conventions, extensions) that are associated with the resource representation, in addition to those defined by the media type and possibly other mechanisms.

To request one or more profiles, a query parameter "profile" can be used:

include::requirements/building-blocks/query-param-profile/REQ_definition.adoc[]

include::recommendations/building-blocks/query-param-profile/PER_default.adoc[]

Determining the profile(s) of the response is part of the content negotiation process after the proactive content negotiation as specified by the https://www.rfc-editor.org/rfc/rfc9110.html#name-content-negotiation[HTTP RFC] has been completed. The server determines the applicable profile(s) for the selected media type.

Different media types have different characteristics. A consequence is that it can be impossible to support a profile for a media type or it can be against the design goals of a media type to support a profile.

include::recommendations/building-blocks/query-param-profile/PER_profiles-of-media-type.adoc[]

The server will select the profile(s) of the response, if any, from the list of profiles supported for the media type and resource.

include::recommendations/building-blocks/query-param-profile/REC_negotiation.adoc[]

include::requirements/building-blocks/query-param-profile/REQ_response.adoc[]

include::recommendations/building-blocks/query-param-profile/REC_link-header.adoc[]
16 changes: 13 additions & 3 deletions core/standard/clause_5_conventions.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -53,14 +53,24 @@ In addition, the following link relation types are used for which no applicable

* **parent**: Indicates that the link's context is part of a hierarchy, and that the parent resource in the hierarchy is the link target.

* **http://www.opengis.net/def/rel/ogc/1.0/queryables**: Refers to a resource, for this context, that provides a list of properties that may be used to create a filter expression.

* **root**: Indicates that the link's context is part of a hierarchy, and that the root resource of the hierarchy is the link target.

* **http://www.opengis.net/def/rel/ogc/1.0/sortables**: Refers to a resource, for this context, that provides a list of properties that may be used to create a sortby expression.
* **`http://www.opengis.net/def/rel/ogc/1.0/sortables`**: Refers to a resource, for this context, that provides a list of properties that may be used to create a sortby expression.

* **http://www.opengis.net/def/rel/ogc/1.0/queryables**: Refers to a resource, for this context, that provides a list of properties that may be used to create a filter expression.

* **http://www.opengis.net/def/rel/ogc/1.0/ogc-catalog**: Refers to a resource, for this context, that points to an associated catalog.

Each resource representation includes an array of links. Implementations are free to add additional links for all resources provided by the API. For example, an enclosure link could reference a bulk download of a collection. Or a related link on a record could reference a related record.

=== Profile URIs

The following profile URIs are defined and used in this document.

* **http://www.opengis.net/def/profile/OGC/0/ogc-catalog**: Refers to a profile of a base resource type (e.g. `application/json`) that is a catalog.

* **http://www.opengis.net/def/profile/OGC/0/ogc-record**: Refers to a profile of a base resource type (e.g. `application/geo+json`) that is a record of a catalg.

=== Examples

Most of the examples provided in this Standard are encoded in JSON. JSON was chosen because it is widely understood by implementers and easy to include in a text document. This convention should NOT be interpreted as a requirement that JSON must be used. Implementers are free to use any format they desire as long as there is a Conformance Class for that format and the deployed API advertises its support for the associated Conformance Class.
Expand Down
Loading