From 6e3ed2d4a00596beffa074b1f150db65396cf13b Mon Sep 17 00:00:00 2001 From: nickevansuk <2616208+nickevansuk@users.noreply.github.com> Date: Tue, 7 Jul 2020 16:12:46 +0100 Subject: [PATCH 1/7] Update based on #1423 --- data/ext/pending/issue-1423-examples.txt | 97 +++++++++++++++++++++++- data/ext/pending/issue-1423.ttl | 56 +++++++++++++- 2 files changed, 147 insertions(+), 6 deletions(-) diff --git a/data/ext/pending/issue-1423-examples.txt b/data/ext/pending/issue-1423-examples.txt index 353652509c..8ff7412e1d 100644 --- a/data/ext/pending/issue-1423-examples.txt +++ b/data/ext/pending/issue-1423-examples.txt @@ -6,25 +6,114 @@ See JSON example. MICRODATA: -TODO +Example is JSON-LD only. RDFA: -TODO +Example is JSON-LD only. JSON: + +TYPES: WebAPI, documentation, termsOfService, endpointUrl, apiTransport, conformsTo + +PRE-MARKUP: + +See JSON example. + +MICRODATA: + +Example is JSON-LD only. + +RDFA: + +Example is JSON-LD only. + +JSON: + + + diff --git a/data/ext/pending/issue-1423.ttl b/data/ext/pending/issue-1423.ttl index fb9f8b5983..2fa7213257 100644 --- a/data/ext/pending/issue-1423.ttl +++ b/data/ext/pending/issue-1423.ttl @@ -7,7 +7,11 @@ :category "issue-1423" ; :isPartOf ; :source ; - rdfs:comment "An application programming interface accessible over Web/Internet technologies." ; + rdfs:comment """An application programming interface accessible over Web/Internet technologies. + +The [[documentation]] property gives specific details of the actual endpoint instances, while the [[conformsTo]] property is used to indicate the general standard or specification that the endpoints implement. The [[url]] property indicates a landing page for the API, which is a Web page that can be navigated to in a Web browser to gain access to the API and/or additional information. + + """ ; rdfs:subClassOf :Service . :documentation a rdf:Property ; @@ -18,7 +22,12 @@ :rangeIncludes :CreativeWork, :URL ; :source ; - rdfs:comment "Further documentation describing the Web API in more detail." . + rdfs:comment """A resource that provides further documentation of the services available via the [[WebAPI]], including their operations, parameters etc. + +The [[documentation]] property gives specific details of the actual endpoint instances, while the [[conformsTo]] property is used to indicate the general standard or specification that the endpoints implement. The [[url]] property indicates a landing page for the API, which is a Web page that can be navigated to in a Web browser to gain access to the API and/or additional information. + +Documentation may be expressed in a machine-readable format, such as an OpenAPI (Swagger) description, an OGC GetCapabilities response WFS, ISO-19142, WMS, ISO-19128, a SPARQL Service Description, an OpenSearch or WSDL20 document, a Hydra API description, otherwise in HTML, text or some other informal mode. The [[encodingFormat]] of the [[CreativeWork]] should be used to indicate the use of such formats via their MIME type. + """ . :termsOfService a rdf:Property ; rdfs:label "termsOfService" ; @@ -30,3 +39,46 @@ :source ; rdfs:comment "Human-readable terms of service documentation." . +:endpointUrl a rdf:Property ; + rdfs:label "endpointUrl" ; + :category "issue-1423" ; + :domainIncludes :WebAPI ; + :isPartOf ; + :rangeIncludes :EntryPoint, + :URL ; + :source ; + rdfs:comment "The root location or primary endpoint of the API." . + +:conformsTo a rdf:Property ; + rdfs:label "conformsTo" ; + :category "issue-1423" ; + :domainIncludes :WebAPI ; + :isPartOf ; + :rangeIncludes :URL ; + :source ; + rdfs:comment "The URL reference of an established standard to which the described API conforms, for example `https://jsonapi.org/format/1.0/`, `https://grpc.io/`, or `http://www.hydra-cg.com/spec/latest/core/`." . + +:accessService a rdf:Property ; + rdfs:label "accessService" ; + :category "issue-1423" ; + :domainIncludes :Dataset, + :DataDownload ; + :isPartOf ; + :rangeIncludes :WebAPI ; + :source ; + rdfs:comment "An API that provides access to the dataset." . + +:apiTransport a rdf:Property ; + rdfs:label "apiTransport" ; + :category "issue-1423" ; + :domainIncludes :WebAPI ; + :isPartOf ; + :rangeIncludes :Text ; + :source ; + rdfs:comment "The type of transport used for the API, such as `HTTP`, `HTTPS`, `SMTP`, `MQTT`, `WS`, `WSS`." . + +:version a rdf:Property ; + :domainIncludes :WebAPI . + +:license a rdf:Property ; + :domainIncludes :WebAPI . From d2cb7b1a64c0209a67d30fc08745825ea3662c03 Mon Sep 17 00:00:00 2001 From: nickevansuk <2616208+nickevansuk@users.noreply.github.com> Date: Fri, 7 Aug 2020 15:27:40 +0200 Subject: [PATCH 2/7] Amended to match https://github.com/webapi-discovery/rfcs/pull/17 --- data/ext/pending/issue-1423-examples.txt | 14 +++++--------- data/ext/pending/issue-1423.ttl | 18 +++++++++++++++--- 2 files changed, 20 insertions(+), 12 deletions(-) diff --git a/data/ext/pending/issue-1423-examples.txt b/data/ext/pending/issue-1423-examples.txt index 8ff7412e1d..7477485e49 100644 --- a/data/ext/pending/issue-1423-examples.txt +++ b/data/ext/pending/issue-1423-examples.txt @@ -53,12 +53,8 @@ JSON: "@type": "WebAPI", "name": "Google Knowledge Graph Search API", "description": "The Knowledge Graph Search API lets you find entities in the Google Knowledge Graph. The API uses standard schema.org types and is compliant with the JSON-LD specification.", - "documentation": [ - { - "@type": "CreativeWork", - "encodingFormat": "text/html", - "url": "https://developers.google.com/knowledge-graph/reference/rest/v1" - }, + "documentation": "https://developers.google.com/knowledge-graph/reference/rest/v1", + "endpointDescription": [ { "@type": "CreativeWork", "encodingFormat": "application/json", @@ -66,9 +62,9 @@ JSON: }, { "@type": "CreativeWork", - "encodingFormat": "application/vnd.oai.openapi+json;version=2.0", - "url": "https://api.apis.guru/v2/specs/googleapis.com/kgsearch/v1/swagger.json" - }, + "encodingFormat": "application/vnd.oai.openapi+json;version=3.0", + "url": "https://api.apis.guru/v2/specs/googleapis.com/kgsearch/v1/openapi.json" + } ], "url": "https://developers.google.com/knowledge-graph/", "termsOfService": "https://developers.google.com/knowledge-graph/terms", diff --git a/data/ext/pending/issue-1423.ttl b/data/ext/pending/issue-1423.ttl index 2fa7213257..999d7a7db7 100644 --- a/data/ext/pending/issue-1423.ttl +++ b/data/ext/pending/issue-1423.ttl @@ -22,11 +22,23 @@ The [[documentation]] property gives specific details of the actual endpoint ins :rangeIncludes :CreativeWork, :URL ; :source ; - rdfs:comment """A resource that provides further documentation of the services available via the [[WebAPI]], including their operations, parameters etc. + rdfs:comment """Human-readable documentation of the services available via the [[WebAPI]], including their operations, parameters etc. -The [[documentation]] property gives specific details of the actual endpoint instances, while the [[conformsTo]] property is used to indicate the general standard or specification that the endpoints implement. The [[url]] property indicates a landing page for the API, which is a Web page that can be navigated to in a Web browser to gain access to the API and/or additional information. +[[endpointDescription]] should be used for machine-readable documentation. + """ . + +:endpointDescription a rdf:Property ; + rdfs:label "endpointDescription" ; + :category "issue-1423" ; + :domainIncludes :WebAPI ; + :isPartOf ; + :rangeIncludes :CreativeWork ; + :source ; + rdfs:comment """Machine-readable API definition of the services available via the [[WebAPI]], including their operations, parameters etc. + +Machine-readable formats include OpenAPI (Swagger) description, an OGC GetCapabilities response WFS, ISO-19142, WMS, ISO-19128, a SPARQL Service Description, an OpenSearch or WSDL20 document, or a Hydra API description. The [[encodingFormat]] property of the [[CreativeWork]] should be used to indicate the use of such formats via their MIME type. -Documentation may be expressed in a machine-readable format, such as an OpenAPI (Swagger) description, an OGC GetCapabilities response WFS, ISO-19142, WMS, ISO-19128, a SPARQL Service Description, an OpenSearch or WSDL20 document, a Hydra API description, otherwise in HTML, text or some other informal mode. The [[encodingFormat]] of the [[CreativeWork]] should be used to indicate the use of such formats via their MIME type. +The [[endpointDescription]] property gives specific details of the actual endpoint instances, while the [[conformsTo]] property is used to indicate the general standard or specification that the endpoints implement. """ . :termsOfService a rdf:Property ; From 244be7d574ef3a65f83fd6dd68886b557f502542 Mon Sep 17 00:00:00 2001 From: nickevansuk <2616208+nickevansuk@users.noreply.github.com> Date: Fri, 14 Aug 2020 10:46:05 +0100 Subject: [PATCH 3/7] Removed Hydra and gRPC examples --- data/ext/pending/issue-1423.ttl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/data/ext/pending/issue-1423.ttl b/data/ext/pending/issue-1423.ttl index 999d7a7db7..9edb1f4c88 100644 --- a/data/ext/pending/issue-1423.ttl +++ b/data/ext/pending/issue-1423.ttl @@ -68,7 +68,7 @@ The [[endpointDescription]] property gives specific details of the actual endpoi :isPartOf ; :rangeIncludes :URL ; :source ; - rdfs:comment "The URL reference of an established standard to which the described API conforms, for example `https://jsonapi.org/format/1.0/`, `https://grpc.io/`, or `http://www.hydra-cg.com/spec/latest/core/`." . + rdfs:comment "The URL reference of an established standard to which the described API conforms, for example `https://jsonapi.org/format/1.0/`." . :accessService a rdf:Property ; rdfs:label "accessService" ; @@ -87,7 +87,7 @@ The [[endpointDescription]] property gives specific details of the actual endpoi :isPartOf ; :rangeIncludes :Text ; :source ; - rdfs:comment "The type of transport used for the API, such as `HTTP`, `HTTPS`, `SMTP`, `MQTT`, `WS`, `WSS`." . + rdfs:comment "The type of transport used for the API, such as `HTTP`, `HTTPS`, `SMTP`, `MQTT`, `WS`, `WSS`, `gRPC`." . :version a rdf:Property ; :domainIncludes :WebAPI . From 33b33fe1c26f97becc98d7c982004693dcc42818 Mon Sep 17 00:00:00 2001 From: nickevansuk <2616208+nickevansuk@users.noreply.github.com> Date: Mon, 17 Aug 2020 12:56:45 +0100 Subject: [PATCH 4/7] Simplification of references to documentation and endpointDescription --- data/ext/pending/issue-1423.ttl | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/data/ext/pending/issue-1423.ttl b/data/ext/pending/issue-1423.ttl index 9edb1f4c88..012bda69cf 100644 --- a/data/ext/pending/issue-1423.ttl +++ b/data/ext/pending/issue-1423.ttl @@ -9,8 +9,7 @@ :source ; rdfs:comment """An application programming interface accessible over Web/Internet technologies. -The [[documentation]] property gives specific details of the actual endpoint instances, while the [[conformsTo]] property is used to indicate the general standard or specification that the endpoints implement. The [[url]] property indicates a landing page for the API, which is a Web page that can be navigated to in a Web browser to gain access to the API and/or additional information. - +The [[documentation]] and [[endpointDescription]] properties give specific details of the actual endpoint instances, while the [[conformsTo]] property is used to indicate the general standard or specification that the endpoints implement. The [[url]] property indicates a landing page for the API, which is a Web page that can be navigated to in a Web browser to gain access to the API and/or additional information. """ ; rdfs:subClassOf :Service . @@ -22,10 +21,7 @@ The [[documentation]] property gives specific details of the actual endpoint ins :rangeIncludes :CreativeWork, :URL ; :source ; - rdfs:comment """Human-readable documentation of the services available via the [[WebAPI]], including their operations, parameters etc. - -[[endpointDescription]] should be used for machine-readable documentation. - """ . + rdfs:comment "Human-readable documentation of the services available via the [[WebAPI]], including their operations, parameters etc." . :endpointDescription a rdf:Property ; rdfs:label "endpointDescription" ; @@ -37,8 +33,6 @@ The [[documentation]] property gives specific details of the actual endpoint ins rdfs:comment """Machine-readable API definition of the services available via the [[WebAPI]], including their operations, parameters etc. Machine-readable formats include OpenAPI (Swagger) description, an OGC GetCapabilities response WFS, ISO-19142, WMS, ISO-19128, a SPARQL Service Description, an OpenSearch or WSDL20 document, or a Hydra API description. The [[encodingFormat]] property of the [[CreativeWork]] should be used to indicate the use of such formats via their MIME type. - -The [[endpointDescription]] property gives specific details of the actual endpoint instances, while the [[conformsTo]] property is used to indicate the general standard or specification that the endpoints implement. """ . :termsOfService a rdf:Property ; From c90261b64067a1e1241bf113e4b51d42da079784 Mon Sep 17 00:00:00 2001 From: nickevansuk <2616208+nickevansuk@users.noreply.github.com> Date: Tue, 25 Aug 2020 21:26:37 +0100 Subject: [PATCH 5/7] More general `conformsTo` --- data/ext/pending/issue-1423.ttl | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/data/ext/pending/issue-1423.ttl b/data/ext/pending/issue-1423.ttl index 012bda69cf..f66148c618 100644 --- a/data/ext/pending/issue-1423.ttl +++ b/data/ext/pending/issue-1423.ttl @@ -58,11 +58,13 @@ Machine-readable formats include OpenAPI (Swagger) description, an OGC GetCapabi :conformsTo a rdf:Property ; rdfs:label "conformsTo" ; :category "issue-1423" ; - :domainIncludes :WebAPI ; + :domainIncludes :CreativeWork, + :WebAPI ; :isPartOf ; :rangeIncludes :URL ; :source ; - rdfs:comment "The URL reference of an established standard to which the described API conforms, for example `https://jsonapi.org/format/1.0/`." . + rdfs:comment """The URL reference of an established standard to which the [[Thing]] described conforms. Broadly equivalent to Dublin Core's "[conformsTo](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#http://purl.org/dc/terms/conformsTo]" property. + """ . :accessService a rdf:Property ; rdfs:label "accessService" ; From 7c6560990b440ab79ea7d6bf169be7f8b42634f3 Mon Sep 17 00:00:00 2001 From: nickevansuk <2616208+nickevansuk@users.noreply.github.com> Date: Tue, 10 Nov 2020 14:55:38 +0000 Subject: [PATCH 6/7] Remove references to endpointUrl --- data/ext/pending/issue-1423-examples.txt | 17 +---------------- data/ext/pending/issue-1423.ttl | 12 +----------- 2 files changed, 2 insertions(+), 27 deletions(-) diff --git a/data/ext/pending/issue-1423-examples.txt b/data/ext/pending/issue-1423-examples.txt index d62b958c45..40fcf99066 100644 --- a/data/ext/pending/issue-1423-examples.txt +++ b/data/ext/pending/issue-1423-examples.txt @@ -23,7 +23,6 @@ JSON: "url": "https://developers.google.com/knowledge-graph/", "documentation": "https://developers.google.com/knowledge-graph/reference/rest/v1", "termsOfService": "https://developers.google.com/knowledge-graph/terms", - "endpointUrl": "https://kgsearch.googleapis.com/", "provider": { "@type": "Organization", "name": "Google Inc." @@ -32,7 +31,7 @@ JSON: -TYPES: #eg-0458 WebAPI, documentation, termsOfService, endpointUrl, apiTransport, conformsTo +TYPES: #eg-0458 WebAPI, documentation, termsOfService, apiTransport, conformsTo PRE-MARKUP: @@ -83,20 +82,6 @@ JSON: ], }, "version": "1.0.0", - "endpointUrl": [ - { - "@type": "EntryPoint", - "name": "Production (uses live data)", - "url": "https://kgsearch.googleapis.com/", - "contentType": "application/json" - }, - { - "@type": "EntryPoint", - "name": "Sandbox (uses test data)", - "url": "https://sandbox.kgsearch.googleapis.com/", - "contentType": "application/json" - } - ], "apiTransport": [ "HTTP", "HTTPS" diff --git a/data/ext/pending/issue-1423.ttl b/data/ext/pending/issue-1423.ttl index f66148c618..3225a2d8c2 100644 --- a/data/ext/pending/issue-1423.ttl +++ b/data/ext/pending/issue-1423.ttl @@ -45,16 +45,6 @@ Machine-readable formats include OpenAPI (Swagger) description, an OGC GetCapabi :source ; rdfs:comment "Human-readable terms of service documentation." . -:endpointUrl a rdf:Property ; - rdfs:label "endpointUrl" ; - :category "issue-1423" ; - :domainIncludes :WebAPI ; - :isPartOf ; - :rangeIncludes :EntryPoint, - :URL ; - :source ; - rdfs:comment "The root location or primary endpoint of the API." . - :conformsTo a rdf:Property ; rdfs:label "conformsTo" ; :category "issue-1423" ; @@ -63,7 +53,7 @@ Machine-readable formats include OpenAPI (Swagger) description, an OGC GetCapabi :isPartOf ; :rangeIncludes :URL ; :source ; - rdfs:comment """The URL reference of an established standard to which the [[Thing]] described conforms. Broadly equivalent to Dublin Core's "[conformsTo](https://www.dublincore.org/specifications/dublin-core/dcmi-terms/#http://purl.org/dc/terms/conformsTo]" property. + rdfs:comment """The URL reference of an established standard to which the [[Thing]] described conforms. """ . :accessService a rdf:Property ; From 0cbd36892d9719972e783b9a4e2920fbcbf08c02 Mon Sep 17 00:00:00 2001 From: nickevansuk <2616208+nickevansuk@users.noreply.github.com> Date: Wed, 11 Nov 2020 11:13:26 +0000 Subject: [PATCH 7/7] Fix conflicting example identifier --- data/ext/pending/issue-1423-examples.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/data/ext/pending/issue-1423-examples.txt b/data/ext/pending/issue-1423-examples.txt index 40fcf99066..586aa1c4ca 100644 --- a/data/ext/pending/issue-1423-examples.txt +++ b/data/ext/pending/issue-1423-examples.txt @@ -31,7 +31,7 @@ JSON: -TYPES: #eg-0458 WebAPI, documentation, termsOfService, apiTransport, conformsTo +TYPES: #eg-0464 WebAPI, documentation, termsOfService, apiTransport, conformsTo PRE-MARKUP: