Why does Metaplex official doc omit many details about its token standards in Metadata account?

Question

Right now in March 2024, I can read the official doc of token standards here. The doc says a lot about the fields in the JSON-formatted Metadata account, like name, symbol, description, image, etc.

However, I cannot find the definitions of many commonly-seen fields. Take Programmable Non-Fungible Token standard as an example, I cannot find the definition of fields like primarySaleHappened, collection, etc.

Also, I've viewed metadata of some NFTs on Solana Explorer, and I find the metadata format doesn't follow the token standards defined in the Metaplex official doc. Take Frogana #1854 as an example. The JSON-formatted metadata of it is:

{
  "key": 4,
  "updateAuthority": "FrogGrkB1yGrWFJe45mmhSedMahTzpEt1SAVPbeEUUsw",
  "mint": "FLLyg3KkGCKNtkqtKfhdkkZL4cu5zbqiBM6fGfi8Sgze",
  "data": {
    "name": "Frogana #1854",
    "symbol": "FRG",
    "uri": "https://arweave.net/S0l1vjRbV83_pN0pz4uowKvXCDrFpqZqtsdACBOy6X8",
    "sellerFeeBasisPoints": 0,
    "creators": [
      {
        "address": "AuV8qcAQVnCJr6yU9go6X1VR3MAQZuiDRRS7twhq1qAU",
        "verified": 1,
        "share": 0
      },
      {
        "address": "FrogGrkB1yGrWFJe45mmhSedMahTzpEt1SAVPbeEUUsw",
        "verified": 0,
        "share": 100
      }
    ]
  },
  "primarySaleHappened": 1,
  "isMutable": 0,
  "editionNonce": 255,
  "tokenStandard": 4,
  "collection": {
    "verified": 1,
    "key": "C7on9fL8YFp5W6M7a6SvehMKBppauZXu2eYDTZG4BN2i"
  }
}

But the official doc says the format should be like:

{
  "name": "SolanaArtProject #1",
  "description": "Generative art on Solana.",
  "image": "https://arweave.net/26YdhY_eAzv26YdhY1uu9uiA3nmDZYwP8MwZAultcE?ext=jpeg",
  "animation_url": "https://arweave.net/ZAultcE_eAzv26YdhY1uu9uiA3nmDZYwP8MwuiA3nm?ext=glb",
  "external_url": "https://example.com",
  "attributes": [
    {
      "trait_type": "trait1",
      "value": "value1"
    },
    {
      "trait_type": "trait2",
      "value": "value2"
    }
  ],
  "properties": {
    "files": [
      {
        "uri": "https://www.arweave.net/abcd5678?ext=png",
        "type": "image/png"
      },
      {
        "uri": "https://watch.videodelivery.net/9876jkl",
        "type": "unknown",
        "cdn": true
      },
      {
        "uri": "https://www.arweave.net/efgh1234?ext=mp4",
        "type": "video/mp4"
      }
    ],
    "category": "video"
  }
}

Answer 1

The fields that are missing according to your description were probably just missed when the docs where migrated since the page you linked just describes the off chain part. Ill have them added, but in the meantime

PrimarySaleHappened is a Boolean that is set to true after the nft is sold the first time. I am not aware of projects that actually use it (besides directly setting it to true)

The collection field is a pointer to a public key which groups multiple nfts into one collection. There also is a verified fields which confirms that the nft was added to the collection by the collection owner or a delegate.

Regarding the difference in those two json files:

The solana explorer is mixing on and off-chain data in the same json view. The metaplex definition describes the off chain data only.