What is this new superseded_by metadata field mean and how can I use it?

[jordanpadams]

The latest version of the Registry and API now includes a ops:Provenance/ops:superseded_by field being returned in product metadata. I have some questions about what this field represents:

1. How are these metadata managed? Do nodes add them directly or is
   there some process by which we provide the information to EN which then
   updates the database?

2. Is superseded_by used for all products, or just those which have
   different LIDs for different versions (i.e. are products with identical
   LIDs automatically assumed to be versions of the same product or is the
   relationship between versions of a product dependent upon
   "superseded_by")? If products with identical LIDs are assumed to be
   versions of the same product, does "superseded_by" only have to be
   included in versions of a product for which the LID is different from
   the initial or immediately preceding/subsequent version?

3. Does superseded_by in a particular version of a product reference all
   other versions of that product or does it daisy chain versions together
   by referencing only the subsequent version?

4. Does the Registry draw the reverse association to the one that is
   actually defined (i.e. if superseded_by indicates the next version of a
   product, is the association from a next version to the superseded
   version also drawn)? Is the Registry able to directly identify all
   versions of a particular product or is it only able to identify the
   "adjacent" (preceding and subsequent) versions?

[pds-ops]

Here are some responses to your questions:

1. How are these metadata managed? Do nodes add them directly or is
   there some process by which we provide the information to EN which then
   updates the database?

EN has a script that runs automatically every 45 minutes to add this metadata by looking for any product LIDs that have >1 version_id, figure out the provenance ordering from the version_ids, and then add the appropriate supersedes_by values to the product metadata.

2. Is superseded_by used for all products, or just those which have
   different LIDs for different versions (i.e. are products with identical
   LIDs automatically assumed to be versions of the same product or is the
   relationship between versions of a product dependent upon
   "superseded_by")? If products with identical LIDs are assumed to be
   versions of the same product, does "superseded_by" only have to be
   included in versions of a product for which the LID is different from
   the initial or immediately preceding/subsequent version?

superseded_by is added to all products that have a version that supersedes. We currently don't have a mechanism for tracking products with changing LIDs, but out initial plans are to have a separate CSV tracking this information, or have an interim product which includes a reference to the product that supersedes it. The latter proposal is being worked out by IMG in the DDWG.

3. Does superseded_by in a particular version of a product reference all
   other versions of that product or does it daisy chain versions together
   by referencing only the subsequent version?

It currently daisy chains versions together. superseded_by only refers to the direct product version that supersedes it.

4. Does the Registry draw the reverse association to the one that is
   actually defined (i.e. if superseded_by indicates the next version of a
   product, is the association from a next version to the superseded
   version also drawn)? Is the Registry able to directly identify all
   versions of a particular product or is it only able to identify the
   "adjacent" (preceding and subsequent) versions?

Yes! There is an API endpoint to return all past versions of a particular product:

/products/{identifier}/all

where {identifier} can be either a LID or LIDVID