Metadata for services: keyword encoding guidance example for INSPIRE Part D.4 uses character string when INSPIRE recommend gmx:anchor

[Sgaff]

Hi,

In our Keyword element, for service metadata, we have an example encoding guidance of how to encode spatial data service category. Our current example however, encodes the spatial data service category keyword as a character string, whereas the INSPIRE 2017 TG recommends that the the keyword be encoded as a gmx:anchor referencing the INSPIRE Spatial Data Service Category codelist e.g <gmx:Anchor xlink:href="http://inspire.ec.europa.eu/metadatacodelist/SpatialDataServiceCategory/humanCatalogueViewer">humanCatalogViewer</gmx:Anchor>

This would be a minor change to the encoding guidance and would not involve any other textual changes, but would bring us directly in line with INSPIRE recommended best practice.

Therefore, I propose a small edit to our encoding guidance to reflect this.

Thanks

Sean

[PeterParslow]

@Sgaff could you label this? That should help us as we begin to resolve issues

[PeterParslow]

I agree that we should make this change although it is only an INSPIRE Recommendation (not requirement) TG Recommendation C.8: metadata/2.0/rec/common/use-anchors-for-cv-keywords.

This affects examples 2, 3, 4 and 5 (the recommendation doesn't only apply to Spatial data service category)

As our guidelines item 3 says Where keywords do originate from a controlled vocabulary the encoding shown in Example Two shall be used, I would see it as breaking: an XML instance that is valid to our encoding guidelines now would not be valid after we make this change.

[PeterParslow]

Primarily Example two, but also Examples three & four.

Also separate the two sentences in item 1 of the Encoding Guidance, and bring item 3 up, to give:

1. The GEMINI2 keyword item comprises keyword value(s) and, conditionally, the specification of an originating controlled vocabulary.
2. Where keywords do originate from a controlled vocabulary the encoding shown in Example Two shall be used.
3. If keywords are not selected from a controlled vocabulary the encoding shown in Example One shall be used.
   etc...

We consider this "non breaking" because the "shall" cannot be validated, being conditional on whether the term is in a controlled vocab. Perhaps drop from "shall" to "should". INSPIRE D4 keywords: it's a recommendation. Note: doing that would mean it's not a breaking change.

[PeterParslow]

The example "numbers" weren't appearing in the HTML output; tried to fix that - awaiting deployment to DEV to see if it worked (due to ifdef statements?)
Fixed snippets for examples 2 & 3 (there aren't examples 4 & 5 as far as I can see)
Tweaked the "encoding guidelines" wording as discussed above. Also fixed the statement about encoding when more than one keyword is from the same vocab.

Removed reference to the "incorrect" example five, which we presumably removed already.

BUT actually, I can't see how the "include" statements in the asciidoc file relate to the files they claim to include & yet result in what I see in the output! Lines 163-181 of keyword.asciidoc should appear for datasets, and apparently include "dataset-keyword-freetext.xml" twice and then dataset-keyword-controlled. dataset-freetext.xml says "satellite imagery" & "earth observation"; both outputs https://agiorguk.github.io/gemini/1063-gemini-services.html#6 & https://agiorguk.github.io/gemini/1062-gemini-datasets-and-data-series.html#6 show the same as each other - but quite different from the snippets (in the main branch) @archaeogeek : could you have a look at this last aspect?

[PeterParslow]

@archaeogeek is there a place to see the HTML output of the dev branch?

[archaeogeek]

@archaeogeek is there a place to see the HTML output of the dev branch?

@PeterParslow the only way of doing this is to switch to the dev branch in the URL and then view the source of the page, eg https://agiorguk.github.io/gemini-dev/1062-gemini-datasets-and-data-series.html for the dev version of https://agiorguk.github.io/gemini/1062-gemini-datasets-and-data-series.html. Alternatively if you're able to build it locally then the html files are generated in your local folder

[archaeogeek]

@PeterParslow Looking into the issue with the incorrect keyword examples showing, in my local copy I have fixed the issue with the free text example showing twice, BUT there does seem to be a wider problem of the dataset variants being overwritten by the services variants, which is why you're seeing the same text in both cases. I honestly can't believe I would have missed this if it was a problem from the word go, so I'm trying to debug what's going on!

[archaeogeek]

@PeterParslow can you review this and see if it still needs to be open please?

[PeterParslow]

Needs to stay open. There are currently no examples visible at https://agiorguk.github.io/gemini-dev/1063-gemini-services.html#6 and the issue still exists in main https://agiorguk.github.io/gemini/1063-gemini-services.html#6

This is true even if I 'view source' of the DEV HTML. so I'm not sure that the tag/include combination is working for this one.

[archaeogeek]

Needs to stay open. There are currently no examples visible at https://agiorguk.github.io/gemini-dev/1063-gemini-services.html#6 and the issue still exists in main https://agiorguk.github.io/gemini/1063-gemini-services.html#6

This is true even if I 'view source' of the DEV HTML. so I'm not sure that the tag/include combination is working for this one.

Can you have another look please? I've just forced a re-run of the action

[PeterParslow]

Thanks. I can now see the examples in the DEV HTML.
Please leave open & with me - I need to now fix the example to address this issue.

[PeterParslow]

See #140 of branch "Peter issue 29"

[PeterParslow]

Still to decide (in comment on July 29, 2021): whether to change "shall" to "should" in the encoding guidance, because the condition cannot be tested (whether the keyword is from a controlled vocabulary or not)

Implemented in DEV: changes to examples 2 & 3 for datasets, example 2 for services.
Still to pull into DEV: changes to examples 3 & 4 for services - I'd left that pull request as 'draft' (#135); changed that just today

[PeterParslow]

Issue remains in live example 4 - which claims to be an example of keywords from two controlled vocabularies, but does not cite the first one. Also, does not use the Anchor encoding for either.
Draft PR 135 creates a couple of Anchors, but doesn't put in a citation for humanCatalogueViewer