reference: FBC property updates

- Add docs about `olm.csv.metadata` property.
- Note deprecation of `olm.bundle.object` property.
- Remove documentation about the "ref"-based `olm.bundle.object`
  property variant.

Signed-off-by: Joe Lanford <[email protected]>

content/en/docs/Reference/file-based-catalogs.md

@@ -387,6 +387,21 @@ The `olm.gvk.required` property [cue][cuelang-spec] schema is:
 }
 ```
 
+#### `olm.csv.metadata`
+
+`olm.csv.metadata` properties are used to include informational metadata about a bundle. This property is optional, and
+there can be at most one of these properties per bundle. Bundles that include this property should not include any
+`olm.bundle.object` properties. This property supersedes the `olm.bundle.object` property.
+
+> **NOTE**: Core OLM does not require a `olm.csv.metadata` property to be included on bundles. However, the OLM Package
+> Server (used by tooling such as the kubectl operator plugin and the OpenShift console) does require these properties
+> to be able to serve metadata about the packages in a catalog. In order to satisfy the needs of the package server, catalog
+> maintainers should use this property to include the CSV metadata for all bundles that are channel heads.
+
+As of `opm` version 1.28.0, this property is automatically generated by when migrating SQLite catalogs with `opm migrate`
+and when rendering SQLite catalogs and registry+v1 bundles with `opm render`. Catalogs containing `olm.csv.metadata`
+properties must be served by `opm` binaries with version at least `1.28.0`.
+
 #### `olm.constraint`
 
 An [`olm.constraint` property][generic-constraint-ep] defines a dependency constraint of a particular type.
@@ -552,40 +567,27 @@ Example:
 [generic-constraint-ep]: https://github.com/operator-framework/enhancements/blob/master/enhancements/generic-constraints.md
 [compound-constraint-ep]: https://github.com/operator-framework/enhancements/blob/master/enhancements/compound-bundle-constraints.md
 
-#### `olm.deprecated`
+#### `olm.bundle.object` (deprecated)
 
-An `olm.deprecated` property defines an `olm.bundle` object which is not installable. Historically, bundle deprecation mechanisms required this property on the `olm.bundle` object(s). This was necessary for SQLite-based catalogs that required all `olm.bundle` objects contributing to valid upgrade edges be present to avoid foreign key violations.
-
-For file-based catalogs, we can simply omit the `olm.bundle` and maintain a valid upgrade graph. Since this property no longer serves any function in file-based catalogs, `opm render` will exclude `olm.bundle`s that contain this property.
-
-#### `olm.bundle.object` (alpha)
-
-`olm.bundle.object` properties are used to inline (or reference) a bundle's manifests directly in the catalog.
+`olm.bundle.object` properties are used to inline a bundle's manifests directly in the catalog.
 
 > **NOTE**: Core OLM does not require `olm.bundle.object` properties to be included on bundles. However, the OLM Package
 > Server (used by tooling such as the kubectl operator plugin and the OpenShift console) does require these properties
 > to be able to serve metadata about the packages in a catalog. In order to satisfy the needs of the package server, catalog
 > maintainers should use this property to include the CSV for all bundles that are channel heads.
 >
-> This property is in _alpha_ because it will likely be rendered obsolete when updates can be made to the OLM Package
-> Server to no longer require manifests in the catalog.
+> This property is _deprecated_ because it causes major performance issues when loading and serving file-based catalogs.
+> The `olm.csv.metadata` property, which serves the exact same purpose, should be used instead.
 
 A bundle object property can contain inlined data using the `value.data` field, which must be the base64-encoded string
 of that manifest.
 
-Alternately, a bundle object property can be a reference to a file relative to the location of the file in which the
-bundle is declared. Any referenced files must be within the catalog root.
-
 The `olm.bundle.object` property [cue][cuelang-spec] schema is:
 ```cue
 
 #PropertyBundleObject: {
   type: "olm.bundle.object"
-  value: #propertyBundleObjectRef | #propertyBundleObjectData
-}
-
-#propertyBundleObjectRef: {
-    ref: string & !=""
+  value: #propertyBundleObjectData
 }
 
 #propertyBundleObjectData: {