Support Publisher information in the API

[mrshll1001]

On a recent call with implementors who were working on implementing the UK Profile, it came to light that we were all expecting that the API specification should include some fields for describing the publisher.

Other standards usually include this in their packaging schemas, making it part of the response or publication metadata.

• 360Giving
• OCDS

This might not necessarily work for HSDS due to not having a packaging schema. So I think we have a few options if we want to address this in the short term:

• Include a publisher object as part of the root (/) API response.
• Add a publisher object to the Page object used to wrap API responses to other endpoints

There could also be other options, and these are not mutually exclusive. We should also determine what format publisher should take. Should it be a few bare-minimum fields for brevity and being to-the-point, or should it be an instance of Organization allowing for a rich description of the publisher using HSDS standard fields?

[MikeThacker1]

It would be good to see publisher which we will probably add to the UK profile at first. If there is an associated data structure likely to be adopted in a future version of HSDS, it would be good to use that.

I can see a case for including all fields/properties that are shown in the current dashboard. That is:

• Publisher name
• Publisher website URL
• Developer name
• Developer website URL
• Descriptive text (as shown in the dashboard's "Summary" column)

[dan-odsc]

@devinbalkind @mrshll1001 @greggish @MikeThacker1 @Cskyleryoung

This is the first issue created since we've had the committee in place, so keen to ensure if follows the process

It has been 'Triaged' (we created it), 'Incubated' (not sure about this term though @devinbalkind) and we've labelled it 'minor' so is now at stage 3 'Prioritize' which I've created as a label and applied.

Next is 'technical committee review' then 'proposal' which is where I think we'll need to work out how we 'Technical Stewards' and you 'The committee' work together.

I've added the sections from the proposal doc to help us consider this. It could be worth us looking at each section and thinking about how/if the committee feeds in to each?

Summary

• No more than a 150 word summary of the proposed changes, the proposal motivation, and how it will benefit HSDS and the Open Referral community.

Background and Motivation

The problem we’re trying to solve

• Describe the problem and its implications/impact.

• What are people currently prevented from doing due to this problem and what impact does it have on their daily operation?

The benefits of the proposed update

• Describe the benefits undertaking this work will accrue.

The evidence for the need

• Include details of why this is needed. If the previous sections have been filled out thoroughly, then this may be as simple as summarising the key points from each and drawing the implications out.

Proposal Details

• This section should include high level details of what changes you are proposing to the HSDS Specification.

• In some cases, the committee defer to the Technical Steward to work out low-level implementation details such as schema structures and API design. You should not feel pressure to include thorough details of data modelling and API design, rather you should express what you need changing in each of these areas.

• If you are willing and able to include specific proposals for e.g. schema properties and/or API features then you are welcome to write them here as suggestions for the committee which the Technical Steward will take on board.

Schema changes

• Include details of what changes to the HSDS schemas you would like to see
• You can list these in tables as well as in text, and include examples if you have them
• You may want to have subsections for proposing changes to existing fields, new fields on existing schemas, and new schemas if your proposal adds them

API Changes

• Include details of what changes to the HSDS API specifications you are proposing or would like to see
• You can list these in tables as well as in text, and include examples
• You may want to have subsections for proposing changes to existing API calls, new arguments or parameters on existing calls, and new calls if your proposal adds them

[You should use additional subsections for your Proposal if needed]

Further Considerations

• Dependencies
• Describe any related areas that are affected by this work

Risks

• Consider the risks associated with the work. Things that could go wrong and the subsequent consequences.

Documentation

• Does there need to be documentation in terms of the process followed throughout the work (for future reference) and/or to support the use of its outputs?

Considerations for existing Profiles

• Does this feature affect the implementation of any existing prominent HSDS profiles? E.g. does it “backport” features from a Profile into the main specification? Does it introduce a conflicting way of achieving a similar goal? If so, how would you expect the Profile maintainers to respond?

Considerations for existing Publishers

• Does any existing HSDS data in use today suddenly become invalid against the new schema if your proposal is accepted? If so, how are you expecting publishers to respond?

• Does your proposal introduce any new optional features which would be useful for existing use cases and publishers? If so, how are you expecting publishers to begin using the new features? What is your broad estimate of the effort involved for them?

Considerations for Data Users

• Do these changes allow data users to do new things? Or do certain things easier?
• Does this introduce new levels of complexity for data users?

[dan-odsc]

Do we think the committee would like to be more involved/hands with assessing issues at the level of the three sections below, or are seeing these as something we (technical stewards) lead on and run by the committee for comments/input?

Background and Motivation

• The problem we’re trying to solve
• Describe the problem and its implications/impact.
• What are people currently prevented from doing due to this problem and what impact does it have on their daily operation?

The benefits of the proposed update

• Describe the benefits undertaking this work will accrue.

The evidence for the need

• Include details of why this is needed. If the previous sections have been filled out thoroughly, then this may be as simple as summarising the key points from each and drawing the implications out.

[devinbalkind]

Thanks for tagging me in here.

I think we're still in the Issue Clarification period on this. During this period we should develop a good idea of what is being proposed without having a finalized, codified proposal.

Mike suggested an approach and fields that he'd like to see included. Is that what is going to be proposed?

The ODSC template you posted seems very thorough. If the people who want to address this issue want to use that template I think that'd be awesome. But I also think if you just wanted to post a concrete solution to the issue: a description of the approach and schema, maybe that'd be sufficient.

[kathryn-ods]

Possibly relates #524