Skip to content

docs/emitters: no refine step reads TypeCommon.Sensitive #895

Open

Description

@OmarAlJarrah

Problem

This describes the IR as #592 leaves it: that PR lowers format: password to these fields at every position and documents them as below.

The IR carries redaction in two fields:

  • TypeCommon.Sensitive — whole-type redaction, shared by every type whose Base reaches a sensitive one (ir/typedef.go).
  • Property.Secret — the per-use form. A value whose type is Sensitive is redacted whether or not it is set (ir/property.go).

docs/emitters/ reads neither in its canonical step list (docs/emitters/refine/steps.md). The only redaction it describes is in the worked example in docs/emitters/targets/go/models.md: "password (Secret) gets a redacting String()". An emitter that follows the document therefore redacts by Property.Secret alone. It prints in clear every value the IR marks through the type instead:

  • a property whose type is a sensitive component ({$ref: Pw} reached through a nullable oneOf, or an allOf over one $ref);
  • a list element or map value whose type is sensitive (items: {type: string, format: password});
  • a parameter whose type is sensitive. ir.Parameter has no per-use field at all (openapi: promote x-sensitive, and give a secret parameter an IR home #578), so the type is its only carrier;
  • anything a future Smithy compiler lowers from @sensitive, which Smithy allows only on shapes.

Reproduction

openapi: 3.1.0
info: {title: t, version: "1"}
paths: {}
components:
  schemas:
    Pw: {type: string, format: password}
    User:
      type: object
      properties:
        tokens: {type: array, items: {type: string, format: password}}
        backup: {oneOf: [{$ref: '#/components/schemas/Pw'}, {type: 'null'}]}

With #592, morphic compile marks the tokens element type and Pw sensitive: true, and both properties secret: false. Under that example's rule, neither field of User is redacted.

Proposal

Add a refine step to docs/emitters/refine/steps.md, for example LowerRedaction, that reads Property.Secret and the Sensitive bit along a type's Base chain. It should decide:

  • what redaction means for a field, a collection element, a map value and a parameter: a redacting String()/GoString(), request and response logging, error messages;
  • whether a redacted collection prints its length or nothing;
  • that a parameter's redaction is read from its type until openapi: promote x-sensitive, and give a secret parameter an IR home #578 gives it a field.

Then reword docs/emitters/targets/go/models.md so its example states both sources.

Acceptance

  • docs/emitters/refine/steps.md names the step, what it reads, and what it lowers to.
  • The example in docs/emitters/targets/go/models.md and the step agree.

Activity

  1. added
    priority:P2Rarer spec shapes, or an IR decision to settle before the emitter
    on Oct 19, 2026
  2. changed the title [-]docs/emitter-design: no refine step reads TypeCommon.Sensitive[/-] [+]docs/emitters: no refine step reads TypeCommon.Sensitive[/+] on Nov 1, 2026
  3. OmarAlJarrah commented on Nov 1, 2026

    @OmarAlJarrah
    MemberAuthor

    #1229 gives ir.Parameter a Secret, so the proposal's last point changes: a parameter's redaction is read from Parameter.Secret or its type, as a property's is, and no longer from its type alone. Its $ref case is covered too, since a parameter reading a Sensitive component now states Secret itself. Parameter redaction belongs to the step this issue asks for; what a target does with the stability tier the same PR adds is #1222.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    priority:P2Rarer spec shapes, or an IR decision to settle before the emittertype:docsDocumentation only

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions