openapi: 3.1.0
info:
  title: SPARQL 1.1 Protocol
  description: |
    SPARQL 1.1 Protocol is a W3C Recommendation that defines how to convey
    SPARQL queries and updates between clients and SPARQL processors over
    HTTP. It defines two operations — `query` and `update` — each of which
    can be invoked over HTTP with several encodings of the SPARQL string.

    This OpenAPI description models only the protocol operations explicitly
    defined in https://www.w3.org/TR/sparql11-protocol/. It does not model
    any vendor-specific authentication scheme; the spec leaves authentication
    to implementations ("implementations may choose to use HTTP authentication
    mechanisms or other implementation-defined mechanisms"). The example
    server is the public DBpedia SPARQL endpoint which accepts query
    requests without authentication.

    The Graph Store HTTP Protocol (a sibling specification at
    https://www.w3.org/TR/sparql11-http-rdf-update/) is not modeled here.
  version: "1.1"
  contact:
    name: W3C SPARQL Working Group
    url: https://www.w3.org/TR/sparql11-protocol/
  license:
    name: W3C Document License
    url: https://www.w3.org/Consortium/Legal/2015/doc-license
servers:
  - url: https://dbpedia.org
    description: Public DBpedia SPARQL endpoint (no auth)
  - url: https://{host}
    description: Generic SPARQL 1.1 endpoint
    variables:
      host:
        default: example.org
        description: Hostname of a SPARQL 1.1 endpoint
tags:
  - name: Query
    description: SPARQL query operation
  - name: Update
    description: SPARQL update operation
paths:
  /sparql:
    get:
      tags:
        - Query
      summary: Execute a SPARQL query via GET
      description: |
        Executes a SPARQL query passed as the `query` URL parameter. The
        query string MUST be percent-encoded. Optional `default-graph-uri`
        and `named-graph-uri` parameters may be repeated to specify the
        RDF dataset against which the query is evaluated.
      operationId: queryGet
      parameters:
        - name: query
          in: query
          required: true
          description: A SPARQL query string, percent-encoded
          schema:
            type: string
          example: SELECT * WHERE { ?s ?p ?o } LIMIT 10
        - name: default-graph-uri
          in: query
          required: false
          description: IRI of a graph to include in the default graph (repeatable)
          schema:
            type: array
            items:
              type: string
              format: uri
          style: form
          explode: true
        - name: named-graph-uri
          in: query
          required: false
          description: IRI of a graph to include as a named graph (repeatable)
          schema:
            type: array
            items:
              type: string
              format: uri
          style: form
          explode: true
        - name: Accept
          in: header
          required: false
          description: Preferred response media type
          schema:
            type: string
            enum:
              - application/sparql-results+json
              - application/sparql-results+xml
              - application/sparql-results+csv
              - application/sparql-results+tsv
              - application/rdf+xml
              - text/turtle
      responses:
        '200':
          description: Successful query result
          content:
            application/sparql-results+json:
              schema:
                $ref: '#/components/schemas/SparqlResultsJson'
            application/sparql-results+xml:
              schema:
                type: string
            application/sparql-results+csv:
              schema:
                type: string
            application/sparql-results+tsv:
              schema:
                type: string
            application/rdf+xml:
              schema:
                type: string
            text/turtle:
              schema:
                type: string
        '400':
          description: Malformed query
        '500':
          description: Query request refused
    post:
      tags:
        - Query
      summary: Execute a SPARQL query via POST
      description: |
        Executes a SPARQL query via POST. Two encodings are defined by the
        SPARQL 1.1 Protocol:

        * `application/x-www-form-urlencoded` — the body carries the same
          parameters as the GET variant (`query`, `default-graph-uri`,
          `named-graph-uri`).
        * `application/sparql-query` — the body IS the SPARQL query string,
          in UTF-8, and `default-graph-uri` / `named-graph-uri` may still
          appear in the URL query string.
      operationId: queryPost
      parameters:
        - name: default-graph-uri
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              format: uri
          style: form
          explode: true
        - name: named-graph-uri
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              format: uri
          style: form
          explode: true
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  description: SPARQL query string
                default-graph-uri:
                  type: array
                  items:
                    type: string
                    format: uri
                named-graph-uri:
                  type: array
                  items:
                    type: string
                    format: uri
          application/sparql-query:
            schema:
              type: string
              description: SPARQL query string (UTF-8)
            example: SELECT * WHERE { ?s ?p ?o } LIMIT 10
      responses:
        '200':
          description: Successful query result
          content:
            application/sparql-results+json:
              schema:
                $ref: '#/components/schemas/SparqlResultsJson'
            application/sparql-results+xml:
              schema:
                type: string
        '400':
          description: Malformed query
  /sparql/update:
    post:
      tags:
        - Update
      summary: Execute a SPARQL update
      description: |
        Executes a SPARQL update. Two encodings are defined by the SPARQL 1.1
        Protocol:

        * `application/x-www-form-urlencoded` — the body carries the
          `update`, `using-graph-uri`, and `using-named-graph-uri`
          parameters.
        * `application/sparql-update` — the body IS the SPARQL update
          string, in UTF-8.

        Many implementations expose update on a distinct path (e.g.
        `/sparql/update`) or require authentication; this is
        implementation-defined.
      operationId: update
      parameters:
        - name: using-graph-uri
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              format: uri
          style: form
          explode: true
        - name: using-named-graph-uri
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              format: uri
          style: form
          explode: true
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - update
              properties:
                update:
                  type: string
                  description: SPARQL update string
                using-graph-uri:
                  type: array
                  items:
                    type: string
                    format: uri
                using-named-graph-uri:
                  type: array
                  items:
                    type: string
                    format: uri
          application/sparql-update:
            schema:
              type: string
              description: SPARQL update string (UTF-8)
            example: INSERT DATA { <urn:s> <urn:p> "o" }
      responses:
        '200':
          description: Update successful
        '204':
          description: Update successful, no content
        '400':
          description: Malformed update
        '401':
          description: Update refused (authentication required)
components:
  schemas:
    SparqlResultsJson:
      type: object
      description: |
        SPARQL Query Results JSON Format, per
        https://www.w3.org/TR/sparql11-results-json/
      required:
        - head
      properties:
        head:
          type: object
          properties:
            vars:
              type: array
              items:
                type: string
            link:
              type: array
              items:
                type: string
                format: uri
        results:
          type: object
          properties:
            bindings:
              type: array
              items:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/RdfTerm'
        boolean:
          type: boolean
          description: Present for ASK queries
    RdfTerm:
      type: object
      required:
        - type
        - value
      properties:
        type:
          type: string
          enum:
            - uri
            - literal
            - bnode
        value:
          type: string
        datatype:
          type: string
          format: uri
        'xml:lang':
          type: string