Fix the upstream format support + add tests & examples

Signed-off-by: Radoslav Dimitrov <radoslav@stacklok.com>

Author: rdimitrov

examples/README.md

@@ -115,7 +115,9 @@ syncPolicy:
 - Creating curated/filtered subsets
 - Registry federation scenarios
 
-**Note:** Upstream format conversion is not yet fully implemented. Use Git or File sources for production.
+**Format Structure:**
+The upstream format uses a wrapper structure with `version`, `meta`, and `data` sections (see `examples/upstream-registry.json`).
+Each server follows the MCP 2025-10-17 schema with `$schema`, `packages[]`, and `_meta` extensions for ToolHive-specific metadata (tier, status, tools, etc.).
 
 ---
 
@@ -256,23 +258,33 @@ filter:
 3. Tag include (empty = include all)
 4. Tag exclude
 
+### Data Format Examples
+
+See the example files for format reference:
+- **ToolHive format** (`examples/toolhive-registry.json`): Flat structure with servers as an object/map
+- **Upstream format** (`examples/upstream-registry.json`): Wrapper structure with meta/data sections and MCP 2025-10-17 schema
+
 ### Git Version Pinning
 
 ```yaml
-source:
- git:
- repository: https://github.com/stacklok/toolhive.git
+registries:
+ - name: my-registry
+ format: toolhive # or "upstream"
+ git:
+ repository: https://github.com/stacklok/toolhive.git
 
- # Option 1: Track latest on a branch
- branch: main
+  # Option 1: Track latest on a branch
+  branch: main
 
- # Option 2: Pin to a release tag
- tag: v1.2.3
+  # Option 2: Pin to a release tag
+  tag: v1.2.3
 
- # Option 3: Pin to exact commit
- commit: abc123def456
+  # Option 3: Pin to exact commit
+  commit: abc123def456
 
- path: pkg/registry/data/registry.json
+ path: pkg/registry/data/registry.json
+ syncPolicy:
+ interval: "30m"
 ```
 
 ---