Skip to content
Permalink
Browse files

feat(api-v2): Control JSON-LD nesting via an HTTP header (DSP-1084) (#…

  • Loading branch information
benjamingeer committed Nov 18, 2020
1 parent 9170419 commit b13eecfcbdb3b535cac2cdfaa59fd0a3929736cb
Showing with 1,403 additions and 210 deletions.
  1. +12 −0 docs/03-apis/api-v2/introduction.md
  2. +389 −0 test_data/metadataE2EV2/metadata-flat.jsonld
  3. +394 −0 test_data/metadataE2EV2/metadata.ttl
  4. +28 −0 webapi/src/main/scala/org/knora/webapi/OntologySchema.scala
  5. +2 −2 webapi/src/main/scala/org/knora/webapi/http/handler/KnoraExceptionHandler.scala
  6. +270 −70 webapi/src/main/scala/org/knora/webapi/messages/util/rdf/JsonLDUtil.scala
  7. +25 −13 webapi/src/main/scala/org/knora/webapi/messages/util/rdf/RdfFormatUtil.scala
  8. +5 −1 webapi/src/main/scala/org/knora/webapi/messages/v2/responder/KnoraRequestV2.scala
  9. +7 −5 webapi/src/main/scala/org/knora/webapi/messages/v2/responder/KnoraResponseV2.scala
  10. +2 −2 ...i/src/main/scala/org/knora/webapi/messages/v2/responder/ontologymessages/OntologyMessagesV2.scala
  11. +1 −1 ...i/src/main/scala/org/knora/webapi/messages/v2/responder/resourcemessages/ResourceMessagesV2.scala
  12. +35 −1 webapi/src/main/scala/org/knora/webapi/routing/RouteUtilV2.scala
  13. +30 −99 webapi/src/test/scala/org/knora/webapi/e2e/v2/MetadataRouteV2E2ESpec.scala
  14. +1 −1 webapi/src/test/scala/org/knora/webapi/e2e/v2/ResourcesRouteV2E2ESpec.scala
  15. +82 −1 webapi/src/test/scala/org/knora/webapi/messages/util/rdf/JsonLDUtilSpec.scala
  16. +115 −9 webapi/src/test/scala/org/knora/webapi/messages/util/rdf/KnoraResponseV2Spec.scala
  17. +1 −1 webapi/src/test/scala/org/knora/webapi/messages/util/rdf/RdfFormatUtilSpec.scala
  18. +2 −2 webapi/src/test/scala/org/knora/webapi/messages/util/rdf/jenaimpl/BUILD.bazel
  19. +2 −2 webapi/src/test/scala/org/knora/webapi/messages/util/rdf/rdf4jimpl/BUILD.bazel
@@ -74,6 +74,18 @@ set of RDF triples, an equivalent JSON-LD response can explicitly
provide data in a hierarchical structure, with objects nested inside
other objects.

### Hierarchical vs. Flat JSON-LD

The client can choose between hierarchical and flat JSON-LD. In hierarchical
JSON-LD, entities with IRIs are inlined (nested) where they are used. If the
same entity is used in more than one place, it is inlined only once, and other
uses just refer to its IRI. In Knora's flat JSON-LD, all entities with IRIs are located
at the top level of the document (in a `@graph` if there is more than one of them).
This setting does not affect blank nodes, which are always inlined (unlike in standard
flat JSON-LD). Knora ontologies are always returned in the `flat` rendering; other kinds
of responses default to `hierarchical`. To use this setting, submit the HTTP header
`X-Knora-JSON-LD-Rendering` with the value `hierarchical` or `flat`.

## Knora IRIs

Resources and entities are identified by IRIs. The format of these IRIs

Large diffs are not rendered by default.

Large diffs are not rendered by default.

@@ -72,6 +72,23 @@ case object MarkupAsStandoff extends MarkupRendering
*/
case object NoMarkup extends MarkupRendering

/**
* A trait representing options that affect the format of JSON-LD responses.
*/
sealed trait JsonLDRendering extends SchemaOption

/**
* Indicates that flat JSON-LD should be returned, i.e. objects with IRIs should be referenced by IRI
* rather than nested. Blank nodes will still be nested in any case.
*/
case object FlatJsonLD extends JsonLDRendering

/**
* Indicates that hierarchical JSON-LD should be returned, i.e. objects with IRIs should be nested when
* possible, rather than referenced by IRI.
*/
case object HierarchicalJsonLD extends JsonLDRendering

/**
* Utility functions for working with schema options.
*/
@@ -118,4 +135,15 @@ object SchemaOptions {
def renderMarkupAsStandoff(targetSchema: ApiV2Schema, schemaOptions: Set[SchemaOption]): Boolean = {
targetSchema == ApiV2Complex && schemaOptions.contains(MarkupAsStandoff)
}

/**
* Determines whether flat JSON-LD should be returned, i.e. objects with IRIs should be referenced by IRI
* rather than nested.
*
* @param schemaOptions the schema options submitted with the request.
* @return `true` if flat JSON-LD should be returned.
*/
def returnFlatJsonLD(schemaOptions: Set[SchemaOption]): Boolean = {
schemaOptions.contains(FlatJsonLD)
}
}
@@ -32,7 +32,7 @@ import spray.json.{JsNumber, JsObject, JsString, JsValue}

/**
* The Knora exception handler is used by akka-http to convert any exceptions thrown during route processing
* into HttpResponses. It is brought implicitly into scope at the top level [[KnoraLiveService]].
* into HttpResponses. It is brought implicitly into scope by the application actor.
*/
object KnoraExceptionHandler extends LazyLogging {

@@ -156,7 +156,7 @@ object KnoraExceptionHandler extends LazyLogging {
// ... and the HTTP status code.
HttpResponse(
status = httpStatus,
entity = HttpEntity(ContentType(MediaTypes.`application/json`), jsonLDDocument.toCompactString)
entity = HttpEntity(ContentType(MediaTypes.`application/json`), jsonLDDocument.toCompactString(false))
)
}

0 comments on commit b13eecf

Please sign in to comment.