# Swift Evolution Metadata Proposed Changes

**URL:** <https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779>\
**Category:** Swift Website\
**Created:** [March 19, 2024, 9:22am UTC](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779 "2024-03-19T09:22:42Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![James\_Dempsey](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/james_dempsey/32/14336_2.png) [@James\_Dempsey](https://forums.swift.org/u/James_Dempsey)\
**Post date:** [March 19, 2024, 9:22am UTC](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/1 "2024-03-19T09:22:42Z")

</div>

The [Swift Evolution Dashboard](https://swift.org/swift-evolution) is driven by a JSON file of proposal metadata available at `https://download.swift.org/swift-evolution/proposals.json`.

In addition, a few other projects in the Swift community are clients of this file.

The current schema has been in place for a number of years now without change. It is missing recent fields like upcoming feature flags, includes outdated fields, and lacks top-level information such as the extraction date and repository SHA the metadata is based on.

This proposal describes intended changes to the metadata schema as well as a transition plan to minimize disruption for clients.

Your feedback on the changes and transition plan are welcome.

All review feedback should be either on this forum thread or, if you would like to keep your feedback private, directly to me by [forum message](https://forums.swift.org/u/James_Dempsey).

Thank you!

* * *

## Transition Plan

### Review Period

There will be a one month review period on the proposed changes to give community members an opportunity to review and provide feedback.

All known client projects of the existing file will be contacted via GitHub issues.

The review period begins today, March 19, 2024 and runs until April, 19, 2024.

### Transition Period

After feedback from the review period is incorporated, there will be a 90-day transition period where the existing and new file schemas will be generated.

- The existing file will continue to be available at:  
`https://download.swift.org/swift-evolution/proposals.json`

- The new file will be available at:  
`https://download.swift.org/swift-evolution/v1/evolution.json`

- During the transition period, the existing `proposals.json` file will include added fields but will not remove or change the structure of any existing fields, so as to not break existing clients.

- The schema version will have a major version of '0' beginning with '0.1.0'

### Transition Completion

At the end of the transition period, the existing metadata file no longer be updated.

- The `proposals.json` file will be replaced with a permanent file that includes a message and the URL of the new metadata file.

- Fields that will no longer be part of the schema will be removed.

- The schema version will reach 1.0.

* * *

## Proposed Change Overview

### 1. Top-level JSON Object

The current JSON file `proposals.json` contains an array of proposal objects at its root.

The biggest structural change would be to make the root a JSON object with a `proposals` key containing the proposals array.

This allows adding top-level fields such as the extraction date and SHA of the repository commit the metadata is based on.

### 2. New file name

Name the new file `evolution.json` to signify the difference from `proposals.json`.

The new name helps indicate that the file contains metadata beyond just the proposals. It also makes it easy to differentiate between the legacy format and the new format.

### 3. Individual field changes

There are a number of individual field changes described in the section _Detailed Individual Field Changes_ below.

* * *

## Detailed Individual Field Changes

### Top-Level Field Additions

All top-level fields are new to the schema.

#### Proposal Metadata

- `proposals`: An array of proposal metadata objects that is currently the root of the `proposals.json` file.

#### Extraction Details

- `creationDate`: An ISO 8601 date string of when the metadata was generated.

- `commit`: The `swift-evolution` repository commit hash used to generate the metadata.

- `toolVersion`: The version of the extraction tool that created the file.

- `schemaVersion`: The version of the schema used in the file.

#### Aggregate Values

- `implementationVersions`: An array of strings containing a uniqued list of versions found in proposals with “Implemented” status, sorted from lowest to highest version.

### SE Proposal Metadata Changes

#### Support multiple release managers

Some evolution proposals have multiple release managers. Currently only the first is included in the metadata.

- Add `releaseManagers` as an array of release managers.

- Remove `releaseManager` field.

Both keys would be generated during the transition period.

#### Add support for upcoming feature flags

- Add an `upcomingFeatureFlag` field.

Since most proposals do not have an upcoming feature flag, this will be an optional field.

This field consists of a JSON object with two fields:

- `flag`: The flag itself

- `enabledInLanguageMode` : Language mode version when feature is always enabled. Field is omitted when there is no announced language mode.

- `available` : Optional field containing the language release version (e.g. "5.10") when the flag is available, if not the same as the release in which the feature is implemented.

**For example:**

```swift
"upcomingFeatureFlag" : {
  "flag" : "BareSlashRegexLiterals",
  "enabledInLanguageMode" : "6"
}

```

#### Changes to errors and warnings

1. Add a `code` field

2. Add a `recoverySuggestion` field.

3. Remove `stage` field.

#### Remove leading dot from status values

- Replace status value strings like `".accepted"` with dot-less strings like `"accepted"`

#### Add a diagnostic string for the error state of status

- Add `reason` key to status object when status state is 'error'

#### Remove unused fields from TrackingBug

- Remove `assignee`, `radar`, `resolution`, `status`, `title`, and `updated` fields

#### Add support for proposal review discussions

- Add a `discussions` field.

In the proposal file, the header field is 'Review' but is defined as the discussion about the proposal. For clarity in the metadata, the field name will be `discussions`.

This field is an array of JSON objects with two fields:

- `name`: The name of the discussion "pitch" "review" "acceptance"

- `link` : The link to the discussion.

**For example:**

```json
"discussions" : [
  {
    "name" : "pitch",
    "link" : "https://forums.swift.org/t/pitch-usability-of-global-actor-isolated-types/70799"
  },
  {
    "name" : "review",
    "link" : "https://forums.swift.org/t/se-0434-usability-of-global-actor-isolated-types/71187"
  },
]

```

Discussions about this addition:  
[original proposal post](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/19)  
[additional commentary](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/25)

#### Add support for previous proposal IDs

- Add a `previousProposalIDs` field.

A proposal can have an optional list of proposals that form a 'line of succession'. For example, part of a previous proposal may be extracted and pitched as a separate proposal. The criteria is described in more detail in the Swift Evolution [proposal template](https://github.com/apple/swift-evolution/blob/main/proposal-templates/0000-swift-template.md).

This field is an optional array of proposal ID strings extracted from the 'Previous Proposal' header field.

Discussions about this addition:  
[original proposal post](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/19)  
[additional commentary](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/25)

* * *

## Schema Summary

### Top level object:

```json
{
   "creationDate": String, // (ISO-8601 date format)
   "commit": String,
   "implementedVersions": [String],
   "proposals": [Proposal],
   "schemaVersion": String,
   "toolVersion": String
}

```

### Proposal object:

```json
{
  "id": String, // SE-NNNN, e.g. "SE-0147"
  "title": String,
  "summary": String,
  "link": String,
  "sha": String, // SHA of the proposal's Markdown file's latest update
  "authors": [// [Proposal.Person]
    {
      "name": String,
      "link": String // warns on absence
    }
  ],
  "reviewManagers": [// [Proposal.Person]
    {
      "name": String,
      "link": String // warns on absence
    }
  ],
  "status": { // Proposal.Status
      "state": String, // Status state name, e.g. "implemented"
      "start": String?, // ISO 8601 date string, key only present for status states with dates
      "end": String?, // ISO 8601 date string, same as above
      "version": String?, // swift version, e.g. "3.0.2", present only for 'implemented' state
      "reason": String? // reason for error state, present only for 'error' state
    }
  },
  "discussions": [// [Proposal.Discussion] A list of the related proposal discussions
    {
      "name": String, // "Pitch", "Review", "Acceptance", ...
      "link": String
    }
  ],
  "trackingBugs": [// [Proposal.TrackingBug]?
    {
      "id": String,
      "link": String,
    }
  ],
  "implementation": [// [Proposal.Implementation]?
    {
      "type": String, // "commit" | "pull"
      "account": String,
      "repository": String,
      "id": String
    }
  ],
  "previousProposalIDs": [String]?, // IDs of proposals that form a line of succession to this proposal
  "upcomingFeatureFlag" : { // [Proposal.UpcomingFeatureFlag]?
    "flag" : String
    "enabledInLanguageMode" : String?, // Language mode version when feature is always enabled. Omitted when there is no announced language mode
    "available" : String?, // Optional field containing the language release version when the flag is available, if not the same as the release in which the feature is implemented.

  },
  "warnings": [// [Proposal.Issue]?, key omitted if no values
    {
      "code": Int, // unique identifier across warnings and errors
      "kind": "warning", // differentiates this from an error
      "message": String, // human-readable description of what's wrong
      "recoverySuggestion": String // human-readable description of how to address the issue
    }
  ],
  "errors": [// [Proposal.Issue]?, key omitted if no values
    {
      "code": Int, // unique identifier across warnings and errors
      "kind": "error", // differentiates this from an error
      "message": String, // human-readable description of what's wrong
      "recoverySuggestion": String // human-readable description of how to address the issue
    }
  ]
}

```

* * *

### Revisions:

#### 3/20/24

- Changed top-level field names
  - From `sha` to `commit`
  - From `extractionDate` to `creationDate`

#### 3/23/24

- Removed section on using default `Codable` structure for `status` object
- Added an optional `reason` field for error status
- Changed `untilLanguageMode` to `enabledInLanguageMode` to match the LSG's preferred naming.

#### 4/1/24

- Fix typo in domain name of `download.swift.org`.

#### 4/4/24

- Updated proposed fields for `upcomingFeatureFlag`
  - Add optional `available` field for flags that are available after proposal implementation version
  - Make `enabledInLanguageMode` field optional

#### 4/12/24

- Add proposed field for `discussions`
- Add proposed field for `previousProposalIDs`

---

<div class="post-metadata">

**Author:** ![ole](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/ole/32/18720_2.png) [@ole](https://forums.swift.org/u/ole)\
**Post date:** [March 19, 2024, 4:19pm UTC](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/2 "2024-03-19T16:19:02Z")

</div>

Thank you for doing a transition period, giving other clients time to adapt to the changes. As the maintainer of [an Alfred workflow for querying Swift Evolution proposals](https://github.com/attaswift/alfred-swift-evolution), I really appreciate this. Special thanks to @James_Dempsey for proactively searching for projects on GitHub that use the existing JSON file and [opening an issue](https://github.com/attaswift/alfred-swift-evolution/issues/2) to alert maintainers about the upcoming change.

As for the proposed changes, +1 on including new metadata such as upcoming feature flags.

If the proposed field names are up for bikeshedding, I don't _love_ a few of them:

- `"extractionDate"`: This focuses on the process by which this file is generated. I don't think this is particularly relevant to users of the file. Maybe something like `"creationDate"` or `"updateDate"` would be better?
- `"sha"` is maybe too specific about a particular hashing algorithm, which isn't super relevant. How about `"commit"`?

But these are very minor complaints. I'm not super strongly against the proposed field names.

---

<div class="post-metadata">

**Author:** ![James\_Dempsey](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/james_dempsey/32/14336_2.png) [@James\_Dempsey](https://forums.swift.org/u/James_Dempsey)\
**Post date:** [March 19, 2024, 5:14pm UTC](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/3 "2024-03-19T17:14:23Z")

</div>

Thank you @ole. It seemed like the best approach to minimize avoidable breakage and also ask for feedback from the people most likely to be interested.

Thank you also for your feedback.

Both field names you mention are ones where I went back and forth between what’s in the proposal and what you suggested. So your feedback is definitely appreciated.

I think `creationDate` and `commit` would be good changes.

---

<div class="post-metadata">

**Author:** ![MahdiBM](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/mahdibm/32/45271_2.png) [@MahdiBM](https://forums.swift.org/u/MahdiBM)\
**Post date:** [March 20, 2024, 12:30am UTC](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/4 "2024-03-20T00:30:20Z")

</div>

As maintainer of [Vapor's Penny](https://github.com/vapor/penny-bot), I also thank you both for the valuable changes and also for proactively notifying us the maintainers.

Reading through your proposed changes, I agree with all of them for the most part.

One concern of mine is:

> [@James\_Dempsey](#):
>
> Swift clients can remove custom Codable implementations for status to automatically decode the file including the status value.

Based on my experience that won't really be a good idea to use the default implementation like that anyway. Because adding a new enum case will fail the whole decoding process, which is suboptimal. Is there something we can do about that? Perhaps, basically making it a "frozen" enum with publicly-known cases?  
I do notice that it's be suboptimal to have constraints of a "frozen" enum, but not sure what will be a better solution. I'm open to suggestions.

About @ole's points, I do agree with what he suggested as well.

Some side-notes:

As I've mentioned on the [swift.org](http://swift.org) repository on GitHub in the past, I wish swift-evolution had CI. Not a great deal but it'd be nice for the proposals-endpoint-users to be able to have more trust on the endpoint, as well as the fact that it makes contributing to the repository easier too by making sure the proposals are already in the correct form before each merge.

And about that ... what is the situation of the proposals.json generator script?  
If i were to guess i'd imagine the current script is written in Python, so more specifically, i'm asking if it's public code, and if it's already written using swift-markdown. It'd be useful for the public to have access to the code so they can contribute.

---

<div class="post-metadata">

**Author:** ![James\_Dempsey](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/james_dempsey/32/14336_2.png) [@James\_Dempsey](https://forums.swift.org/u/James_Dempsey)\
**Post date:** [March 20, 2024, 3:03pm UTC](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/5 "2024-03-20T15:03:19Z")

</div>

Thank you for your feedback @MahdiBM.

Regarding the status field, I believe your assessment is correct.

At a high level, if the Swift Evolution process adds a new status, clients would generally need to update to handle the new status value regardless of the client language. (The evolution dashboard JavaScript maps the status values to human readable strings, for example.)

In a Swift client, it is natural to model the status as an enum.

So, for a Swift client, it would be desirable to have some indication there is a new status value that needs to be handled, but something less severe than having the entire decode fail.

The metadata file generator already defines an "error" status value that is not an actual status in the evolution process.

A Swift client could add a default case that returns the error status value if no other cases match.

That would allow decoding to succeed, but give clients a way to check for status errors.

It would probably be useful for the "error" status value to have an optional associated "reason" string that could contain the reason that status was used, including the name of the unrecognized status: "Found unrecognized status 'rejectedWithExtremePrejudice''". This would also be useful any time the "error" status is used to provide additional diagnostic information.

It is also unfortunate that the default encoding of enums uses the enum value itself as part of the encoded schema. There seems to be no way to get a decoder to report keys and values that are not already defined as coding keys. So, with the default encoding of enums, there does not seem to be any way, even in custom decode methods, to detect new enum values and return an "error" case.

So, that leaves us with the original schema, with the proposed addition of an optional `reason` field to be used with the error status.

```swift
  "status": {
      "state": String, // // Proposal.Status case name, e.g. "implemented" 
      "start": String?, // ISO 8601 date string, key only present for status states with dates
      "end": String?, // ISO 8601 date string, same as above
      "version": String?, // swift version number, e.g. "3.0.2"
      "reason": String?, // optional reason for error status
    }

```

I also think it would make sense to make the full set of possible status values to be public.

And in terms of swift-evolution pre-merge metadata validation and having the metadata generating tool be public, we are on the same page.

Again, thank you for your feedback!

---

<div class="post-metadata">

**Author:** ![James\_Dempsey](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/james_dempsey/32/14336_2.png) [@James\_Dempsey](https://forums.swift.org/u/James_Dempsey)\
**Post date:** [March 23, 2024, 3:36pm UTC](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/6 "2024-03-23T15:36:59Z")

</div>

I've updated the proposal to incorporate feedback to date.

---

<div class="post-metadata">

**Author:** ![Jon\_Shier](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/jon_shier/32/921_2.png) [@Jon\_Shier](https://forums.swift.org/u/Jon_Shier)\
**Post date:** [March 23, 2024, 6:00pm UTC](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/7 "2024-03-23T18:00:20Z")

</div>

> [@James\_Dempsey](#):
>
> `schemaVersion`: The version of the schema used in the file.

Have you decided what versioning strategy you're going to use? I'd recommend at least a major.minor form to separate breaking and non breaking changes.

Is there room in the proposal object to include links to the first toolchains for each platform where the feature is available? Links to release versions, as well as versions of Xcode that integrate the feature, may also be useful.

---

<div class="post-metadata">

**Author:** ![James\_Dempsey](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/james_dempsey/32/14336_2.png) [@James\_Dempsey](https://forums.swift.org/u/James_Dempsey)\
**Post date:** [March 23, 2024, 7:25pm UTC](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/8 "2024-03-23T19:25:37Z")

</div>

> [@Jon\_Shier](#):
>
> Have you decided what versioning strategy you're going to use? I'd recommend at least a major.minor form to separate breaking and non breaking changes.

I'm working on a document regarding versioning, but for the schema version, my thoughts were along the lines you suggest.

A major version bump would mean breaking changes such as removal of fields and changes to the structure. A minor version change would be non-breaking, like adding fields.

> [@Jon\_Shier](#):
>
> Is there room in the proposal object to include links to the first toolchains for each platform where the feature is available? Links to release versions, as well as versions of Xcode that integrate the feature, may also be useful.

The intent is for the original proposal document to be a self-contained source of truth for the proposal metadata.

In terms of links to the first toolchains where the feature is available, do you mean available while it is still proposed / under review?

Once a proposal is implemented, the Swift version is included in the metadata, so a client like the SE Dashboard could potentially construct the appropriate link to the release version.

---

<div class="post-metadata">

**Author:** ![Jon\_Shier](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/jon_shier/32/921_2.png) [@Jon\_Shier](https://forums.swift.org/u/Jon_Shier)\
**Post date:** [March 25, 2024, 2:23am UTC](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/9 "2024-03-25T02:23:04Z")

</div>

> [@James\_Dempsey](#):
>
> In terms of links to the first toolchains where the feature is available, do you mean available while it is still proposed / under review?

I guess I go with the latest development toolchain its in during the proposal, or if merged, the mainline toolchain. Then switch to the version toolchains it officially becomes part of until a release, where it would be the Swift and Xcode version

---

<div class="post-metadata">

**Author:** ![James\_Dempsey](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/james_dempsey/32/14336_2.png) [@James\_Dempsey](https://forums.swift.org/u/James_Dempsey)\
**Post date:** [March 26, 2024, 3:55pm UTC](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/10 "2024-03-26T15:55:23Z")

</div>

> [@Jon\_Shier](#):
>
> I guess I go with the latest development toolchain its in during the proposal, or if merged, the mainline toolchain. Then switch to the version toolchains it officially becomes part of until a release, where it would be the Swift and Xcode version

Thanks @Jon_Shier.

The reason I ask is that the _Implementation_ header in the SE proposal was always a link to one or more pr/commits that contained the implementation. That is what is currently extracted. Now sometimes that header contains some explanation of how to use the implementation (e.g. "On `main` using experimental feature flag `ProposedFeature`").

I was thinking that after this initial transition, it would make sense to work with the LSG to standardize what appears in that field or if possibly 'how to use the pre-release feature' which a toolchain link might be a part of should be separate than links to the code that implements the feature.

---

<div class="post-metadata">

**Author:** ![James\_Dempsey](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/james_dempsey/32/14336_2.png) [@James\_Dempsey](https://forums.swift.org/u/James_Dempsey)\
**Post date:** [April 4, 2024, 5:59pm UTC](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/11 "2024-04-04T17:59:46Z")

</div>

Spending more time helping update upcoming feature flags in the source proposals, I have updated the proposal for `upcomingFeatureField`:

First, typically an upcoming feature flag (UFF) is available in the same release that implements the proposal. On occasion, the UFF is not available until a later release. (For example, [SE-0352](https://github.com/apple/swift-evolution/blob/main/proposals/0352-implicit-open-existentials.md#source-compatibility) was implemented in 5.7 but the UFF is not available until 6.0.)

For these cases, the `upcomingFeatureField` metadata will include an optional `available` field.

Second, the `enabledInLanguageMode` field which will often not have a value, will also be an optional field.

Making both optional matches closely with the Upcoming Feature Flag header in the source proposals, where these additional annotations are often not required or present.

---

<div class="post-metadata">

**Author:** ![Victor\_Martins](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/victor_martins/32/23726_2.png) [@Victor\_Martins](https://forums.swift.org/u/Victor_Martins)\
**Post date:** [April 5, 2024, 6:19pm UTC](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/12 "2024-04-05T18:19:30Z")

</div>

It’s awesome to see this discussion about something I’ve been looking at for a while when building [Proposal Monitor](https://apps.apple.com/br/app/proposal-monitor/id6449445305), the app I [just announced on Community Showcase](https://forums.swift.org/t/proposal-monitor-i-built-us-an-app/71107/1). Recently I’ve noticed a few meaningful changes that had impact in the app and agreeing on a schema is the best way to avoid those problems.

I believe the proposed schema is great and improves a lot over the original.

Nonetheless, I’d like to know more about the title and summary fields. Today they contain the markdown version of their contents. Are they going to keep being like this? Should we formalize this somewhere? (Considering my use case I prefer it to keep storing the markdown content)

And I’m not sure if this question fits here, but I’d like to know if changes to the summary parsing could be discussed as some proposals simply have no summary as of now (SE-0425 is an example).

---

<div class="post-metadata">

**Author:** ![James\_Dempsey](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/james_dempsey/32/14336_2.png) [@James\_Dempsey](https://forums.swift.org/u/James_Dempsey)\
**Post date:** [April 5, 2024, 6:55pm UTC](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/13 "2024-04-05T18:55:41Z")

</div>

Thank you for the feedback @Victor_Martins and congratulations on launching your app!

This proposal focuses on schema changes and transitioning to the new schema with the thought that improving individual field content could happen without needing changes to the schema itself.

But yes, both things you mention are open to discussion, separate from the schema changes. Please feel free to start threads here in Swift Website.

I also believe summary parsing could be improved. And it would be good to get feedback regarding markdown versus plain text. (The summary field is an interesting case as the other fields appear on the Swift Evolution dashboard, but the summary is not currently used.)

I also appreciate your feedback on the proposed changes. My hope is that this schema can be used a long while without requiring breaking changes.

---

<div class="post-metadata">

**Author:** ![Victor\_Martins](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/victor_martins/32/23726_2.png) [@Victor\_Martins](https://forums.swift.org/u/Victor_Martins)\
**Post date:** [April 5, 2024, 10:50pm UTC](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/14 "2024-04-05T22:50:04Z")

</div>

> [@James\_Dempsey](#):
>
> congratulations on launching your app!

Thank you! 🙂

> [@James\_Dempsey](#):
>
> This proposal focuses on schema changes and transitioning to the new schema with the thought that improving individual field content could happen without needing changes to the schema itself.

Sorry to insist, but I'd just like to mention that I believe that if the community were to prefer having both a field containing markdown content and a field containing the "raw" content, this would probably result in us having additional fields to accommodate. That's why I thought it could make sense to bring up this discussion on here. But, again, keeping it as it is right now (containing markdown) is totally fine for me. I'll keep an eye if someone proposes a change in another thread like you mentioned.

> [@James\_Dempsey](#):
>
> (The summary field is an interesting case as the other fields appear on the Swift Evolution dashboard, but the summary is not currently used.)

Yeah! And it's not really that much standardized on the proposals themselves. Some of them start with an introduction section, some start with a paragraph and then they write the introduction section, ...

---

<div class="post-metadata">

**Author:** ![James\_Dempsey](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/james_dempsey/32/14336_2.png) [@James\_Dempsey](https://forums.swift.org/u/James_Dempsey)\
**Post date:** [April 6, 2024, 12:05am UTC](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/15 "2024-04-06T00:05:30Z")

</div>

> [@Victor\_Martins](#):
>
> Sorry to insist, but I'd just like to mention that I believe that if the community were to prefer having both a field containing markdown content and a field containing the "raw" content, this would probably result in us having additional fields to accommodate. That's why I thought it could make sense to bring up this discussion on here.

Sorry, I misunderstood what you meant. Potentially adding additional fields is definitely part of the schema discussion.

I think the main downside of providing multiple representations is it provides nearly duplicated data for those fields, especially when one of those fields is the summary, which is already typically the largest amount of data per proposal.

I believe the markdown value provides the most flexibility for a client without duplication.

For example a Swift client can:

1. Use the string as-is. (For example display titles with backticks to indicate code voice)

2. Create an attributed string with `AttributedString(markdown: value)`

3. Get the content string with `NSAttributedString(markdown: value).string`  
(I think the content string is what you mean by the "raw" content.)

There may be use cases I am missing (we have a relatively small group of known clients of this file).

But I believe this provides a good trade-off between file size and flexibility for clients.

(Note that I use `NSAttributedString` in the example for brevity because it has a convenience method. A similar convenience can be written with a few lines using the CharacterView of `AttributedString.characters`.)

---

<div class="post-metadata">

**Author:** ![Victor\_Martins](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/victor_martins/32/23726_2.png) [@Victor\_Martins](https://forums.swift.org/u/Victor_Martins)\
**Post date:** [April 6, 2024, 2:52am UTC](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/16 "2024-04-06T02:52:14Z")

</div>

Yeah, I completely agree with everything you said.

And if there was ever a relevant use case, we could consider having a different URL for each variant (raw or markdown) instead of changing the schema again and having to duplicate most of the content, as you said. I admit I was a bit worried about the conversion from markdown to its content string on other platforms, but I'm probably overthinking since we haven't even heard of those use cases.

---

<div class="post-metadata">

**Author:** ![James\_Dempsey](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/james_dempsey/32/14336_2.png) [@James\_Dempsey](https://forums.swift.org/u/James_Dempsey)\
**Post date:** [April 8, 2024, 10:38pm UTC](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/17 "2024-04-08T22:38:23Z")

</div>

> [@Victor\_Martins](#):
>
> I admit I was a bit worried about the conversion from markdown to its content string on other platforms, but I'm probably overthinking since we haven't even heard of those use cases.

Yes and Markdown is generally well supported across various platforms and languages.

---

<div class="post-metadata">

**Author:** ![James\_Dempsey](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/james_dempsey/32/14336_2.png) [@James\_Dempsey](https://forums.swift.org/u/James_Dempsey)\
**Post date:** [April 8, 2024, 10:50pm UTC](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/18 "2024-04-08T22:50:51Z")

</div>

I have been preparing for the beginning of the transition and have been wondering whether the proposed `recoverySuggestion` field in errors and warnings could be shortened to `suggestion` without losing clarity.

The purpose of this field is to suggest how the reported issue can be fixed in the original Markdown, to make it easier to fix issues with missing or mis-formatted fields.

---

<div class="post-metadata">

**Author:** ![Victor\_Martins](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/victor_martins/32/23726_2.png) [@Victor\_Martins](https://forums.swift.org/u/Victor_Martins)\
**Post date:** [April 9, 2024, 5:25am UTC](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/19 "2024-04-09T05:25:38Z")

</div>

On the details' screen of a proposal on Proposal Monitor I show previous related proposals and the history of discussions. To get this information I download the original markdown from the full proposal and extract the values from the header fields that currently aren't present in the JSON.

For my use case, it would be interesting to have these fields on the schema. So, I propose we add the following fields to each proposal:

```swift
{
  "id": String,
  "title": String,
  ...
  "previousProposalIDs": [String]?,
  "discussions": [ // A list of the related discussions in chronological order
    {
      "title": String, // "Pitch", "Review", "Acceptance", ...
      "link": String
    }
  ]
}

```

Alternatives considered for the first field:

- We could name it `previouslyRelatedProposalIDs`
- We could name it `relatedProposalIDs` and mention both the proposal A in the related proposals list of the proposal B and vice-versa, instead of having only the new proposals pointing at the older ones

Alternatives considered for the second field:

- We could name it `relatedDiscussions` or `discussionHistory`

---

<div class="post-metadata">

**Author:** ![nikolai.ruhe](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/nikolai.ruhe/32/23230_2.png) [@nikolai.ruhe](https://forums.swift.org/u/nikolai.ruhe)\
**Post date:** [April 9, 2024, 11:21am UTC](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779/20 "2024-04-09T11:21:59Z")

</div>

Sorry if I'm just blind but is there documentation of the new (or old) schema somewhere?

For example, I have a question about the semantics of the `"link"` field in the proposals. It seems to be a relative link based on `https://github.com/apple/swift-evolution/blob/main/proposals/`. The link's base is not mentioned in the file. Maybe there could be a top-level `"extractionRoot"` field or similar?

I'm currently only toying around with the metadata. I'd love if there was a basic Swift package to parse the file into proper types. This could also be a great place to find documentation.

[Next page](https://forums.swift.org/t/swift-evolution-metadata-proposed-changes/70779.md?page=2)
