548 add and delete metadata

Introduction

This page documents the eq-author team's shared understanding of how adding, updating and removing metadata will be supported.

The details here are the result of a design session that the team had and the discussions that took place during that session.

Background

Metadata are key value pairs that are supplied to a questionnaire by some external source. Metadata values can be piped into a questionnaire at runtime and can affect the behavior of a questionnaire in terms of its routing and validation.

Changes required

GraphQL schema

type Metadata {
    id: ID!
    key: String 
    alias: String
    type: MetadataType!
    dateValue: Date
    regionValue: Region
    languageValue: Language
    textValue: String
}

enum MetadataType {
    Date
    Text
    Region
    Language
}

# A list of supported regions from ISO_3166-2:GB
enum Region {
    GB_ENG
    GB_GBN
    GB_NIR
    GB_SCT
    GB_WLS
}


# A list of supported language codes from ISO 639-1
enum Language {
    en
    cy
}

# A new field added to query all metadatata values for a questionnaire
extend type Questionnaire {
    metadata: [Metadata!]! # Not nullable should return an empty array if no metadata.
}

extend type Mutation {
    createMetadata(input: CreateMetadataInput!): Metadata!
    updateMetadata(input: UpdateMetadataInput!): Metadata!
    deleteMetadata(input: DeleteMetadataInput!): Metadata
}

input CreateMetadataInput {
    questionnaireId: ID!
}

input DeleteMetadataInput {
    id: ID!
}

input UpdateMetadataInput {
    id: ID!
    key: String
    alias: String
    type: MetadataType!
    dateValue: Date
    regionValue: Region
    languageValue: Language
    textValue: String
}

API changes

metadata

id (pk)	key: String	alias: String	type: Enum	value: String	isDeleted: Bool	QuestionnaireId (fk)
1	ru_ref	Reporting Unit Reference	Text	"1000000000000"	false	1
2	region	Region Code	Region	"GB-GBN"	false	1

Assumptions

• There will not be a composite key on the questionnaire metadata table. This means in theory, you could end up with a situation where the same metadata keys are defined more than once for a questionnaire. The reason for not enforcing this at a DB level is that the UX would not work (being able to add rows) so it is likely that you would have duplicate null keys in the table initially until the keys have been filled in.
• The typeahead will remove previously used metadata keys from it's typeahead list to reduce the changes of users entering the same metadata keys twice.
• Additional safeguards can be coded into Publisher to ensure that the same metadata values are not published twice.
• Newly added metadata entries will default its type to Text. The metadata type is not nullable in the schema so we have something to fall back on if both key and alias are not supplied (e.g. metadata.text_1)