safety-net-blueprint/packages/contracts/overlays/example/modifications.yaml at main · codeforamerica/safety-net-blueprint · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
overlay: 1.0.0
info:
  title: Example State Overlay
  version: 1.0.0
  description: |
    Example overlay demonstrating common state customization patterns.
    Use this as a starting point for your own state-specific overlay.

    Patterns demonstrated:
    - Replacing enum values (terminology changes)
    - Adding properties to existing schemas
    - Adding enum entries to existing lists
    - Using file disambiguation for shared schema names

    Notes on JSONPath targets:
    - Schemas inlined in API specs live under $.components.schemas.*
    - Schemas in shared component files (components/*.yaml) are top-level ($.*)
    - Use "file:" to disambiguate when a schema name appears in multiple files

actions:
  # ============================================================================
  # Terminology Changes
  # Replace enum values to match state-specific terminology
  # ============================================================================

  # States may use different terminology for citizenship status
  # CitizenshipInfo is in persons-openapi.yaml under components/schemas
  - target: $.components.schemas.CitizenshipInfo.properties.status.enum
    file: persons-openapi.yaml
    description: Replace citizenship status values with state-specific terminology
    update:
      - us_citizen
      - lawful_permanent_resident
      - qualified_alien
      - prucol
      - undocumented
      - other

  # States may have their own program names
  # Program is a shared schema in components/common.yaml (top-level)
  - target: $.Program.enum
    file: components/common.yaml
    description: Replace generic program names with state-branded names
    update:
      - snap_state
      - tanf_state
      - medicaid_state
      - general_assistance

  # ============================================================================
  # Property Additions
  # Add state-required fields to existing schemas
  # ============================================================================

  # Many states track county/region for benefit administration
  # Person is in persons-openapi.yaml under components/schemas
  - target: $.components.schemas.Person.allOf.1.properties
    file: persons-openapi.yaml
    description: Add state-specific geographic tracking fields
    update:
      regionCode:
        type: string
        description: State region or county code for benefit administration.
        example: "042"
      regionName:
        type: string
        description: State region or county name.
        example: "Example County"

  # ============================================================================
  # Enum Additions
  # Extend enum lists with state-specific entries
  # ============================================================================

  # States can add explicit properties to flexible schemas
  # UiPermissions has additionalProperties: true, so states define their own fields
  - target: $.components.schemas.UiPermissions
    file: users-openapi.yaml
    description: Add explicit property definitions to UiPermissions for state UI modules
    update:
      type: object
      readOnly: true
      additionalProperties: true
      description: |
        State-specific UI permissions and display data for frontend feature toggling.
        Backend computes these from role and permissions.
      properties:
        availableModules:
          type: array
          items:
            type: string
            enum:
              - cases
              - tasks
              - reports
              - documents
              - scheduling
              - admin
              - state_integration
          description: UI modules available to this user.
        canApproveApplications:
          type: boolean
          description: Whether the user can approve applications.

  # ============================================================================
  # Auth Context Extensions
  # Add claims to JWT/auth context for state-specific authorization
  # ============================================================================

  # BackendAuthContext is a shared schema in components/auth.yaml (top-level)
  - target: $.BackendAuthContext.properties
    file: components/auth.yaml
    description: Add program-based authorization to auth context
    update:
      programs:
        type: array
        items:
          type: string
        description: Programs the user is authorized to access (empty = all programs).
        example: ["snap_state", "tanf_state"]