Search Example: Richer JSON & JSON‐LD 1.0

Description

An example request to the /search endpoint, with a JSON-LD response. This the same request as in the simple JSON example.

This JSON-LD mapping option has the following properties:

• the response is still simple JSON, but different from the current one (having a deeper structure, changing the way individual services are identified and avoiding the usage of ac: prefix);
• a fixed JSON-LD context (for all /search requests) is linked using an HTTP header in the response;
• it requires inference using Audio Commons ontology to derive a complete RDF graph;
• it may not require enriching the Audio Commons ontology with shortcuts that are only relevant to the mediator;
• axiomatic-triples/specific-ontology for the API service can possibly be avoided;
• names of services like Freesound and Jamendo are used in JSON responses both to identify service replies and as prefixes for resources, leading to problematic mapping using JSON-LD 1.0.

Status: missing mapping of meta properties and service identification

Test: JSON-LD expansion to be tested

TODO:

• map meta properties (.meta, .warnings, and .errors)
• represent service provenance (acx:fromService)
• modularize JSON-LD context

Detailed Example

Request: https://m.audiocommons.org/api/v1/search/text/?q=cars&fields=*

JSON-LD Context (e.g., available at http://audiocommons.org/contexts/main.jsonld):

{
  "ac": "http://audiocommons.org/ns/audiocommons#",
  "dc": "http://purl.org/dc/terms/",
  "cc": "https://creativecommons.org/ns#",
  "ccLicenses": "https://creativecommons.org/licenses/by-nc/",

  "service": {"@id": "acx:fromService", "@type": "@id"},
  "contents": "ac:memberNodeAudioCollectionNodeWithNodeContent",
  "num_results": {"@id": "ac:membersCount", "@type": "xsd:int"},
  "results": {"@id": "ac:collectionAsList", "@container": "@list"},

  "id": "@id",
  "homepage": {"@id": "ac:homepage", "@type": "@id"},
  "url": {"@id": "ac:homepage", "@type": "@id"},
  "title": "dc:title",
  "name": "dc:title",
  "description": "dc:description",
  "compiler": {"@reverse": "ac:compiled"},
  "author": "ac:compilerAgentName",
  "author_url": {"@reverse": "ac:compiled", "@type": "@id"},
  "license": "ac:licenseCode",
  "license_deed_url": {"@id": "cc:license", "@type": "@id"},
  "duration": {"@id": "ac:duration", "@type": "xsd:float"},
  "collection_url": {"@id": "ac:principalContainerNodeIsMemberNodeOf", "@type": "@id"},
  "tags": "ac:audioCategoryWithLabel",
  "timestamp": {"@id": "ac:isPublishedAudioManifetationOfAudioPublicationWithTimeInstantInXSDDateTime", "@type": "xsd:dateTime"},

  "digitalSignalProperties": {"@id": "ac:encodesDigitalSignal", "@type": "@id"},
  "bitdepth": {"@id": "ac:bitsPerSample", "@type": "xsd:int"},
  "channels": {"@id": "ac:channels", "@type": "xsd:int"},
  "samplerate": {"@id": "ac:sampleRate", "@type": "xsd:int"},

  "audioFiles": {"@id": "ac:availableAsAudioFile", "@type": "@id"},
  "download_url": "@id",
  "filesize": {"@id": "ac:fileSize", "@type": "xsd:int"},
  "bitrate": {"@id": "ac:bitRate", "@type": "xsd:int"},
  "format": {"@id": "ac:format", "@type": "@id"},

  "Jamendo": "http://audiocommons.org/ns/jamendo/serviceOrSounds/",
  "Freesound": "http://audiocommons.org/ns/freesound/serviceOrSounds/",
}

Response Headers (excerpt):

Content-Type: application/json
Link: <http://audiocommons.org/contexts/main.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

Response:

{
  "meta": {
    "response_id": "f81a72b4-d715-47ad-a9aa-c5d85b69ab91",
    "status": "FI",
    "n_expected_responses": 3,
    "n_received_responses": 3,
    "sent_timestamp": "2017-10-06 10:57:29.670769",
    "collect_url": "https://m.audiocommons.org/api/v1/collect/?rid=f81a72b4-d715-47ad-a9aa-c5d85b69ab91",
    "current_timestamp": "2017-10-06 10:57:31.639568"
  },
  "contents": [
    {
      "service": "Jamendo",
      "num_results": null,
      "results": [
        {
          "author": "Nappasantana",
          "id": "Jamendo:1016857",
          "license": "BY-NC-SA",
          "name": "KCAGM & MOB",
          "audioFiles": [
            "https://mp3d.jamendo.com/download/track/1016857/mp32/"
          ],
          "tags": [
            "cars",
            "mob",
            "clothes"
          ],
          "url": "http://www.jamendo.com/track/1016857"
        },
        {
          "author": "Naturalbodyartist",
          "id": "Jamendo:1326587",
          "license": "BY-NC-SA",
          "name": "therace",
          "audioFiles": [
            "https://mp3d.jamendo.com/download/track/1326587/mp32/"
          ],
          "tags": [
            "rock",
            "ambient",
            "cars",
            "race",
            "victory"
          ],
          "url": "http://www.jamendo.com/track/1326587"
        },
        {
          "author": "Out Of Orion (Ox3)",
          "id": "Jamendo:1318996",
          "license": "BY-NC-ND",
          "name": "Cars On The Road",
          "audioFiles": [
            "https://mp3d.jamendo.com/download/track/1318996/mp32/"
          ],
          "tags": [
            "ambient",
            "chillout",
            "soundscape",
            "road",
            "cars",
            "soundeffects"
          ],
          "url": "http://www.jamendo.com/track/1318996"
        }
      ]
    },
    {
      "service": "Freesound"
      "num_results": 6611,
      "results": [
        {
          "author": "15050_Francois",
          "author_url": "https://www.freesound.org/apiv2/users/15050_Francois/",
          "collection_url": null,
          "description": "The ambience/room tone of a car, switched off and closed windows next to a primary school while the children are having break time. A more quiet version of my other \"Inside Car Next To School Ambience\" recording",
          "duration": 248.5,
          "id": "Freesound:326146",
          "license": "BY-NC",
          "license_deed_url": "http://creativecommons.org/licenses/by-nc/3.0/",
          "name": "Inside Car Ambience Next to School More Quiet Version.wav",
          "digitalSignalProperties": {
            "bitdepth": 24,
            "channels": 2,
            "samplerate": 48000.0
          },
          "audioFiles": [
            {
              "download_url": "https://freesound.org/data/previews/326/326146_5622605-hq.ogg",
              "format": "wav",
              "bitrate": 2250,
              "filesize": 71568736
            }
          ],
          "tags": [
            "primary",
            "Next",
            "Environment",
            "Location",
            "Vehicle",
            "Ambience",
            "Public",
            "OWI",
            "Cars",
            "breaktime",
            "cars",
            "School",
            "Car",
            "Inside",
            "Quiet",
            "break",
            "lunch",
            "Road",
            "primary-school",
            "Street",
            "Landscape",
            "Motor",
            "Transport"
          ],
          "timestamp": "2015-10-26 14:11:30",
          "url": "https://freesound.org/people/15050_Francois/sounds/326146/"
        },
        {
          "author": "jungh001",
          "author_url": "https://www.freesound.org/apiv2/users/jungh001/",
          "collection_url": null,
          "description": "Famous Nürburgring Nordschleife, Cars from 1925- 1940.",
          "duration": 24.2347,
          "id": "Freesound:170992",
          "license": "CC0",
          "license_deed_url": "http://creativecommons.org/publicdomain/zero/1.0/",
          "name": "Nordschleife_Vorkriegsrennwagen_1.wav",
          "digitalSignalProperties": {
            "bitdepth": 24,
            "channels": 2,
            "samplerate": 48000.0
          },
          "audioFiles": [
            {
              "download_url": "https://freesound.org/data/previews/170/170992_142024-hq.ogg",
              "format": "wav",
              "bitrate": 2250,
              "filesize": 6980752
            }
          ],
          "tags": [
            "bentley",
            "Vintage",
            "cars",
            "driveby",
            "Cars",
            "mercedes",
            "racing"
          ],
          "timestamp": "2012-12-03 10:49:33",
          "url": "https://freesound.org/people/jungh001/sounds/170992/"
        },
        {
          "author": "semenov_nick",
          "author_url": "https://www.freesound.org/apiv2/users/semenov_nick/",
          "bitdepth": 32,
          "bitrate": 3001,
          "channels": 2,
          "collection_url": "https://freesound.org/apiv2/packs/21409/",
          "description": "Recorded in Moscow. Cars across on street.",
          "duration": 127.321,
          "filesize": 48915012,
          "format": "wav",
          "id": "Freesound:385285",
          "license": "CC0",
          "license_deed_url": "http://creativecommons.org/publicdomain/zero/1.0/",
          "name": "01 - Cars across_city.wav",
          "preview_url": "https://freesound.org/data/previews/385/385285_3596390-hq.ogg",
          "samplerate": 48000.0,
          "tags": [
            "city",
            "urban",
            "traffic",
            "street",
            "cars"
          ],
          "timestamp": "2017-03-24 12:47:58",
          "url": "https://freesound.org/people/semenov_nick/sounds/385285/"
        }
      ]
    }
  ],
  "warnings": [
    {
      "service": "Jamendo",
      "messages": [
        "Can't return unsupported field bitdepth",
        "Can't return unsupported field samplerate",
        "Can't return unsupported field bitrate",
        "Can't return unsupported field collection_url",
        "Can't return unsupported field timestamp",
        "Can't return unsupported field description",
        "Can't return unsupported field license_deed_url",
        "Can't return unsupported field filesize",
        "Parameter 'size' not supported",
        "Can't return unsupported field collection",
        "Can't return unsupported field duration",
        "Can't return unsupported field channels",
        "Can't return unsupported field format",
        "Can't return unsupported field author_url"
      ],
    },
    {
      "service": "Freesound",
      "messages": [
        "Can't return unsupported field collection"
      ],
    },
    {
      "service": "Europeana",
      "messages": [
        "Can't return unsupported field bitdepth",
        "Can't return unsupported field samplerate",
        "Can't return unsupported field bitrate",
        "Can't return unsupported field collection_url",
        "Can't return unsupported field timestamp",
        "Can't return unsupported field description",
        "Can't return unsupported field license_deed_url",
        "Can't return unsupported field filesize",
        "Can't return unsupported field tags",
        "Can't return unsupported field collection",
        "Can't return unsupported field format",
        "Can't return unsupported field duration",
        "Can't return unsupported field channels",
        "Can't return unsupported field author_url"
      ]
    }
  ],
  "errors": []
}