search

ietf-tools / relaton-data-ieee

3 stars 5 forks source link

Incomplete relation #6

Closed strogonoff closed 2 years ago

strogonoff commented 2 years ago

In rfcsubseries, relation’s bibitem specifies a complete citation:

https://github.com/ietf-ribose/relaton-data-rfcsubseries/blob/main/data/BCP0016.yaml#L23

In ieee, it’s just a formatted reference:

https://github.com/ietf-ribose/relaton-data-ieee/blob/main/data/IEEE_PC57-12-90_D-6.2021-06.yaml#L56

Can we expect a consistent shape of this property? Which one of the above would it be?

From what I can see, https://github.com/relaton/relaton-models/blob/main/grammars/biblio.rnc#L445 specifies bibitem to be a BibliographicItem instance.

ronaldtse commented 2 years ago

@strogonoff a BibliographicItem supports a formattedRef which is the "display string" version of a bibliographic item. Both items as shown are valid.

In rfcsubseries, we made the decision to include the full RFC reference within a subseries items (e.g. BCP) because these items do not have content, and rely on its included references for content.

In ieee, we will not include the full references due to content size. It may also lead to content loops (doc A "updates" doc B which is "superseded" by doc A).

strogonoff commented 2 years ago

@ronaldtse does this mean literally all properties in BibliographicItem are optional? And if I expect a BibliographicItem instance, it can be an empty object with just a formattedRef?

ronaldtse commented 2 years ago

Yes. There are occasions when people provide a bibliographic reference, all we know is a string and nothing more…

strogonoff commented 2 years ago

That shouldn’t be a BibliographicItem, but BibliographicItemReference or something along those lines. Then, if you want, you can define relation to be a union of those types.

When all properties are optional, it dramatically reduces the usefulness of a spec. By that logic, BibXML service can state that it returns a BibliographicItem and just return a formatted ref (or empty object) to comply. If consumer gets a BibliographicItem, there are minimum expectations about it.

On 3 Jan 2022, at 9:33 AM, Ronald Tse @.***> wrote:

 Yes. There are occasions when people provide a bibliographic reference, all we know is a string and nothing more…

— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.

ronaldtse commented 2 years ago

That shouldn’t be a BibliographicItem, but BibliographicItemReference or something along those lines. Then, if you want, you can define relation to be a union of those types.

Maybe. This could be a good distinction to make.