Adds jsonld context, Adds support for jsonld typed values

[maechler]

Q	A
Bug fix?	no
New feature?	yes
BC breaks?	no
Deprecations?	no
Tests pass?	no
Fixed tickets	-
License	MIT
Doc PR	api-platform/docs#122

This pull request is just an implementation proposal, it is not yet ready to be merged. I have not put any effort into fixing the tests.

This pull request wants to add json-ld typed values: https://www.w3.org/TR/json-ld/#typed-values
e.g.

entity

    /**
     * @var string | array
     *
     * @ApiProperty(iri="http://xmlns.com/foaf/0.1/firstName");
     *
     */
    private $firstName;

    /**
     * @var string | array
     *
     * @ApiProperty(iri="http://xmlns.com/foaf/0.1/lastName", valueType="literal");
     *
     */
    private $lastName;

context

{
    "@context": {
        "@vocab": "http://swissbib-hydra.lo/apidoc.jsonld#",
        "hydra": "http://www.w3.org/ns/hydra/core#",
        "firstName": "http://xmlns.com/foaf/0.1/firstName",
        "lastName": {
            "@id": "http://xmlns.com/foaf/0.1/lastName",
            "@type": "literal"
        }
    }
}

What do you think?

[dunglas]

Can be simplified using elseif.

[dunglas]

This method should be updated too: https://github.com/api-platform/core/blob/master/src/Hydra/Serializer/DocumentationNormalizer.php#L282-L319

[teohhanhui]

What about having these as attributes, so that it can be JSON-LD specific, instead of trying to find a general enough "type" declaration that fits all the formats (sounds like an impossible task).

[maechler]

I can also move it to the attributes. What would be the convention for the name?
Just use "value_type"="something" ?

[teohhanhui]

There is already a hydra_context key, perhaps we can add jsonld_context?

[maechler]

So it would be something like ?

    /**
     * @var string | array
     *
     * @ApiProperty(iri="http://xmlns.com/foaf/0.1/lastName", attributes={"jsonld_context": {"value_type":"literal"}})
     *
     */
    private $lastName;

[dunglas]

Tyes, it looks better!

[teohhanhui]

/**
 * @var string
 *
 * @ApiProperty(iri="http://xmlns.com/foaf/0.1/lastName", attributes={
 *     "jsonld_context"={"@type"="literal"},
 * })
 *
 */
private $lastName;

[maechler]

Looks fine for me, I guess that's the way to go:)

[teohhanhui]

What's set in the jsonld_context attribute should be used as the base. We don't want to limit it to just @type.

[teohhanhui]

See for example how hydra_context is handled in

core/src/Hydra/Serializer/DocumentationNormalizer.php

Lines 209 to 273 in 7ac1866

	/**
	* Gets and populates if applicable a Hydra operation.
	*
	* @param string $resourceClass
	* @param ResourceMetadata $resourceMetadata
	* @param string $operationName
	* @param array $operation
	* @param string $prefixedShortName
	* @param bool $collection
	*
	* @return array
	*/
	private function getHydraOperation(string $resourceClass, ResourceMetadata $resourceMetadata, string $operationName, array $operation, string $prefixedShortName, bool $collection) : array
	{
	if ($collection) {
	$method = $this->operationMethodResolver->getCollectionOperationMethod($resourceClass, $operationName);
	} else {
	$method = $this->operationMethodResolver->getItemOperationMethod($resourceClass, $operationName);
	}
	$hydraOperation = $operation['hydra_context'] ?? [];
	$shortName = $resourceMetadata->getShortName();
	if ('GET' === $method && $collection) {
	$hydraOperation = [
	'hydra:title' => sprintf('Retrieves the collection of %s resources.', $shortName),
	'returns' => 'hydra:PagedCollection',
	] + $hydraOperation;
	} elseif ('GET' === $method) {
	$hydraOperation = [
	'hydra:title' => sprintf('Retrieves %s resource.', $shortName),
	'returns' => $prefixedShortName,
	] + $hydraOperation;
	} elseif ('POST' === $method) {
	$hydraOperation = [
	'@type' => 'hydra:CreateResourceOperation',
	'hydra:title' => sprintf('Creates a %s resource.', $shortName),
	'returns' => $prefixedShortName,
	'expects' => $prefixedShortName,
	] + $hydraOperation;
	} elseif ('PUT' === $method) {
	$hydraOperation = [
	'@type' => 'hydra:ReplaceResourceOperation',
	'hydra:title' => sprintf('Replaces the %s resource.', $shortName),
	'returns' => $prefixedShortName,
	'expects' => $prefixedShortName,
	] + $hydraOperation;
	} elseif ('DELETE' === $method) {
	$hydraOperation = [
	'hydra:title' => sprintf('Deletes the %s resource.', $shortName),
	'returns' => 'owl:Nothing',
	] + $hydraOperation;
	}
	$hydraOperation['@type'] ?? $hydraOperation['@type'] = 'hydra:Operation';
	$hydraOperation['hydra:method'] ?? $hydraOperation['hydra:method'] = $method;
	if (!isset($hydraOperation['rdfs:label']) && isset($hydraOperation['hydra:title'])) {
	$hydraOperation['rdfs:label'] = $hydraOperation['hydra:title'];
	}
	ksort($hydraOperation);
	return $hydraOperation;
	}

[maechler]

Great input! I did not think of that, I updated the pull request.

[teohhanhui]

Anyway, please add some tests. 😄

[maechler]

I will add some tests, probably I'll need some time to have a look at the existing tests.

What about the docs, do you update them or shall I create a pull request there too?

[teohhanhui]

Reverse the order so that what's set in jsonld_context takes precedence.

[maechler]

Ok, I thought in this case it might be better to force @id and @type. But the other way round it leaves more freedom for the developers. I'll change it.

[maechler]

Do I have to take care of the deps='low' build in that case?
It seems like it does not allow entities without ORM annotations.

[teohhanhui]

This should also address #731

@albertedevigo What do you think?

[maechler]

@teohhanhui What about the unit tests?

[teohhanhui]

You should add a test for the JsonLd/ContextBuilder too, perhaps also covering the use case of #731?

[maechler]

@albertedevigo @teohhanhui I added a test for JsonLd/ContextBuilder.

I think #731 can be addressed with this issue. However I think there is also a need for a jsonld context on a resource level. I have created an issue here api-platform/api-platform#93 and now moved to #767.
That would also allow for the alternative use of @reverse described first in the issue.

[dunglas]

Thank you @maechler! Can you open a doc PR on https://github.com/api-platform/docs/ to document this new feature please?

[maechler]

@dunglas Awesome, thanks!
Yes I will. Shall I add a new .md file to the core doc and an own documentation chapter "jsonld context"? I have not found any chapter where it would make sense to add this.

[dunglas]

I think that it deserves a new chapter.