Changes to the way concept relationships are represented in the API

Owned by Mike Cochrane
Last updated: Apr 13, 2021 by Landcare DevopsVersion comment
6 min read

This will be a breaking change to v0.1 of the API.

Overview

Concept relationships show how one name concept relates to another name concept, for example, the parent-child and synonmy type relationships.

The concept relationships are found in the description of a name record under the Concepts element so all endpoints that include a representation of a name would be affected.

Why we are making the change

The current representation of the relationships between concepts is more complex than it needs to be. It repeats the from concepts for each relationship and makes it difficult to know what the to and from directions mean, i.e. is it from the concept to another or from the other concept to it?

Current Concept Structure
<Concept>
	<Name />
	<Publication />
	<FromRelationships>
		<Relationship>
			<FromConcept />
			<ToConcept />
			<Type />
			<IsAction />
			<InUseByProviders />
		</Relationship>
	<ToRelationships>
		<Relationship>
			<FromConcept />
			<ToConcept />
			<Type />
			<IsAction />
			<InUseByProviders />
		</Relationship>
	</ToRelationships>
</Concept>
  • From concepts are repeated including all of their details
  • Two elements to deal with concept relationships
Proposed Concept Structure
<Concept>
	<Name />
	<Publication />
	<Relationships>
		<Relationship>
			<Concept />
			<Type />
			<IsAction />
			<InUseByProviders />
		</Relationship>
	</ToRelationships>
</Concept>
  • The From concept is only shown once and all relationships are shown in one Relationships element with the other end of the relationship
  • The concept element in the relationships is the To concept

This is probably best shown with an example

Current v1.0 API Example

http://data.nzor.org.nz/names/007da152-5435-46da-9489-66331d85871e

<Concept>
  <ConceptId>4caa53dc-4409-474e-a658-bd0f0e68a1fd</ConceptId>
  <Name>
    <NameId>007da152-5435-46da-9489-66331d85871e</NameId>
    <FullName>Luzula campestris var. picta (A.Rich.) Hook.f.</FullName>
    <PartialName>Luzula campestris var. picta</PartialName>
    <CanonicalName>picta</CanonicalName>
    <Rank>variety</Rank>
  </Name>
  <Publication>
    <ReferenceId>81ee01ea-86f1-4f1c-a6df-7907677c1b20</ReferenceId>
    <Type>Generic</Type>
    <Citation>NZFLORA (2012-) New Zealand Plant Names - Name based concepts</Citation>
  </Publication>
  <Orthography />
  <Rank />
  <HigherClassification />
  <FromRelationships>
    <Relationship>
      <FromConcept>
        <ConceptId>4caa53dc-4409-474e-a658-bd0f0e68a1fd</ConceptId>
        <Name>
          <NameId>007da152-5435-46da-9489-66331d85871e</NameId>
          <FullName>Luzula campestris var. picta (A.Rich.) Hook.f.</FullName>
          <PartialName>Luzula campestris var. picta</PartialName>
          <CanonicalName>picta</CanonicalName>
          <Rank>variety</Rank>
        </Name>
        <Publication>
          <ReferenceId>81ee01ea-86f1-4f1c-a6df-7907677c1b20</ReferenceId>
          <Type>Generic</Type>
          <Citation>NZFLORA (2012-) New Zealand Plant Names - Name based concepts</Citation>
        </Publication>
      </FromConcept>
      <ToConcept>
        <ConceptId>21b8f3ba-3853-4314-b7e7-6e019d6bb854</ConceptId>
        <Name>
          <NameId>8ff8a16f-0a36-4315-afc5-4a699fccfe96</NameId>
          <FullName>Luzula campestris (L.) DC.</FullName>
          <PartialName>Luzula campestris</PartialName>
          <CanonicalName>campestris</CanonicalName>
          <Rank>species</Rank>
        </Name>
        <Publication>
          <ReferenceId>81ee01ea-86f1-4f1c-a6df-7907677c1b20</ReferenceId>
          <Type>Generic</Type>
          <Citation>NZFLORA (2012-) New Zealand Plant Names - Name based concepts</Citation>
        </Publication>
      </ToConcept>
      <Type>is parent of</Type>
      <IsActive>true</IsActive>
      <InUseByProviders />
    </Relationship>
    <Relationship>
      <FromConcept>
        <ConceptId>4caa53dc-4409-474e-a658-bd0f0e68a1fd</ConceptId>
        <Name>
          <NameId>007da152-5435-46da-9489-66331d85871e</NameId>
          <FullName>Luzula campestris var. picta (A.Rich.) Hook.f.</FullName>
          <PartialName>Luzula campestris var. picta</PartialName>
          <CanonicalName>picta</CanonicalName>
          <Rank>variety</Rank>
        </Name>
        <Publication>
          <ReferenceId>81ee01ea-86f1-4f1c-a6df-7907677c1b20</ReferenceId>
          <Type>Generic</Type>
          <Citation>NZFLORA (2012-) New Zealand Plant Names - Name based concepts</Citation>
        </Publication>
      </FromConcept>
      <ToConcept>
        <ConceptId>3564fd16-7c30-4366-95d3-67fcbf44b0a8</ConceptId>
        <Name>
          <NameId>9900f6a6-35d6-4839-91e0-458106424ac4</NameId>
          <FullName>Luzula picta A.Rich.</FullName>
          <PartialName>Luzula picta</PartialName>
          <CanonicalName>picta</CanonicalName>
          <Rank>species</Rank>
        </Name>
        <Publication>
          <ReferenceId>81ee01ea-86f1-4f1c-a6df-7907677c1b20</ReferenceId>
          <Type>Generic</Type>
          <Citation>NZFLORA (2012-) New Zealand Plant Names - Name based concepts</Citation>
        </Publication>
      </ToConcept>
      <Type>is synonym of</Type>
      <IsActive>true</IsActive>
      <InUseByProviders />
    </Relationship>
  </FromRelationships>
  <ToRelationships />
  <FromApplications />
  <ToApplications />
  <AddedDate>2012-02-29T12:35:52.25</AddedDate>
  <ModifiedDate>2016-09-07T21:35:27.85</ModifiedDate>
</Concept>

Proposed v1.0 API Example

http://test-data.nzor.org.nz/names/007da152-5435-46da-9489-66331d85871e

<Concept>
  <ConceptId>4caa53dc-4409-474e-a658-bd0f0e68a1fd</ConceptId>
  <Name>
    <NameId>007da152-5435-46da-9489-66331d85871e</NameId>
    <FullName>Luzula campestris var. picta (A.Rich.) Hook.f.</FullName>
    <PartialName>Luzula campestris var. picta</PartialName>
    <CanonicalName>picta</CanonicalName>
    <Rank>variety</Rank>
  </Name>
  <Publication>
    <ReferenceId>81ee01ea-86f1-4f1c-a6df-7907677c1b20</ReferenceId>
    <Type>Generic</Type>
    <Citation>NZFLORA (2012-) New Zealand Plant Names - Name based concepts</Citation>
  </Publication>
  <Orthography />
  <Rank />
  <HigherClassification />
  <Relationships>
    <Relationship>
      <Concept>
        <ConceptId>21b8f3ba-3853-4314-b7e7-6e019d6bb854</ConceptId>
        <Name>
          <NameId>8ff8a16f-0a36-4315-afc5-4a699fccfe96</NameId>
          <FullName>Luzula campestris (L.) DC.</FullName>
          <PartialName>Luzula campestris</PartialName>
          <CanonicalName>campestris</CanonicalName>
          <Rank>species</Rank>
        </Name>
        <Publication>
          <ReferenceId>81ee01ea-86f1-4f1c-a6df-7907677c1b20</ReferenceId>
          <Type>Generic</Type>
          <Citation>NZFLORA (2012-) New Zealand Plant Names - Name based concepts</Citation>
        </Publication>
        <Applications />
      </Concept>
      <Type>is child of</Type>
      <IsActive>true</IsActive>
      <InUseByProviders />
    </Relationship>
    <Relationship>
      <Concept>
        <ConceptId>3564fd16-7c30-4366-95d3-67fcbf44b0a8</ConceptId>
        <Name>
          <NameId>9900f6a6-35d6-4839-91e0-458106424ac4</NameId>
          <FullName>Luzula picta A.Rich.</FullName>
          <PartialName>Luzula picta</PartialName>
          <CanonicalName>picta</CanonicalName>
          <Rank>species</Rank>
        </Name>
        <Publication>
          <ReferenceId>81ee01ea-86f1-4f1c-a6df-7907677c1b20</ReferenceId>
          <Type>Generic</Type>
          <Citation>NZFLORA (2012-) New Zealand Plant Names - Name based concepts</Citation>
        </Publication>
        <Applications />
      </Concept>
      <Type>is synonym of</Type>
      <IsActive>true</IsActive>
      <InUseByProviders />
    </Relationship>
  </Relationships>
  <AddedDate>2012-02-29T12:35:52.25</AddedDate>
  <ModifiedDate>2017-05-16T20:28:06.557</ModifiedDate>
</Concept>