familysearch / gedcomx-rs Goto Github PK

9. Authentication and Authorization

A server MAY require authorization to access certain application states. Authentication and authorization are outside the scope of this specification. OAuth 2 as specified by RFC 6749 is RECOMMENDED as an authentication mechanism.

However three states have OAuth2 links listed as valid transitions. It seems that any links to authentication and authorization resources ought to be implementation-specific extensions as opposed to being in the gedcomx-rs spec itself.

Can application states be extended?

The specification for Link says:

Instances of Link can be reasonably expected as extension elements to any GEDCOM X data type.

I believe that statement should be more explicit.

In gedcomx-java (the canonical implementation of GEDCOM X), anything that supports links inherits from HypermediaEnabledData. There are a number of data types that don't inherit from HypermediaEnabledData and thus don't support links. Why?

The best reason I could see for not supporting links is not supporting extension elements but Address supports extension elements while not supporting links. Was that intentional?

The spec should either say "All data types support links," list data types that do support links, or list data types that don't support it and imply that all others do.

See FamilySearch/gedcomx-java#46

1.3.7 Application Entry Points:

Use of the Collections, Collection, Person, and Source Description application states is RECOMMENDED as entry points.

Does this statement need a reason to support it? Collections, Collection, and Person are fairly obvious but Source Description isn't so obvious. At least to me.

The proposal is to get rid of the parent and spouse wrappers for a person and use links to identify the primary person and how the other persons in the atom:entry relate to each other. E.g.:

<feed>
  ...
  <entry>
    <link rel="self" href="/xt/persons/1"/>
    <link rel="gx:father" href="/xt/persons/2"/>
    <link rel="gx:mother" href="/xt/persons/3"/>
    <gxc:person>
      <link rel="self" href="/xt/persons/1"/>
      ...
    </gxc:person>
    <gxc:person>
      <link rel="self" href="/xt/persons/2"/>
      ...
    </gxc:person>
    <gxc:person>
      <link rel="self" href="/xt/persons/3"/>
      ...
    </gxc:person>
  </entry>
</feed>

Why does gedcomx-rs specify extension elements? All of the extension elements appear to be useful in the core model.

Section 4 of the GEDCOM X RS spec defines the application states, and for each one there is a statement discussing the media types:

Applications that implement the Agent state MUST support the application/x-gedcomx-v1+json media type as defined by the GEDCOM X JSON specification. Support for the application/x-gedcomx-v1+xml media type as defined by GEDCOM X XML is RECOMMENDED.

Why is support for JSON required while XML is only recommended? I'm a fan of JSON myself but this decision still sounds arbitrary to me. Is the justification for this decision documented anywhere?

PlaceDisplayProperties and PlaceDescription.display need to be documented.

The resourceId attribute of ResourceReference and EvidenceReference needs to be added to the RS spec.

See FamilySearch/gedcomx#300