PHPackages fsans/fms-odata-spec-php - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. fsans/fms-odata-spec-php ActiveLibrary[Utility & Helpers](/categories/utility) fsans/fms-odata-spec-php ======================== Shared PHP types and spec definitions for the Claris FileMaker Server OData API. Mirrors @fms-odata/spec-ts (npm) and fms-odata-spec (PyPI). Types + pure helpers only; no HTTP client, no validation framework. 2.0.1(1mo ago)140↓61.7%1[1 issues](https://github.com/fsans/fms-odata-spec/issues)1MITPHPPHP ^8.2CI passing Since Jul 10Pushed 1mo agoCompare [ Source](https://github.com/fsans/fms-odata-spec)[ Packagist](https://packagist.org/packages/fsans/fms-odata-spec-php)[ RSS](/packages/fsans-fms-odata-spec-php/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (2)Versions (4)Used By (1) fms-odata-spec ============== [](#fms-odata-spec) [![npm](https://camo.githubusercontent.com/b6720f8d32cf94c7a70203d4d8b66f4919255598310fbc7f62f7d7d37f2615c0/68747470733a2f2f696d672e736869656c64732e696f2f6e706d2f762f40666d732d6f646174612f737065632d74733f6c6162656c3d6e706d253230253430666d732d6f64617461253246737065632d7473266c6f676f3d6e706d)](https://www.npmjs.com/package/@fms-odata/spec-ts)[![PyPI](https://camo.githubusercontent.com/61b969279b3b190b052b52359bb0f17776ff500a956f40eb8fab965292e123d3/68747470733a2f2f696d672e736869656c64732e696f2f707970692f762f666d732d6f646174612d737065633f6c6162656c3d50795049253230666d732d6f646174612d73706563266c6f676f3d70797069)](https://pypi.org/project/fms-odata-spec/)[![Packagist](https://camo.githubusercontent.com/43460915aa4aba607a717e6ec31690586f9b668d661c438a360128ea707f22f4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6673616e732f666d732d6f646174612d737065632d7068703f6c6162656c3d5061636b61676973742532306673616e73253246666d732d6f646174612d737065632d706870266c6f676f3d7061636b6167697374)](https://packagist.org/packages/fsans/fms-odata-spec-php) A canonical base reference for the **Claris FileMaker Server OData API**, intended as the single source of truth that downstream libraries (MCP servers, JavaScript wrappers, and any future wrappers) conform to and evolve against. Purpose ------- [](#purpose) This project provides a **unified source of conventions and a version-aware capability list** for the Claris FileMaker Server OData API. It serves as a common platform to unify FileMaker OData implementations across different languages, runtimes, and tool ecosystems. The Claris OData API has evolved across server versions (2023, 2024, 2025, 2026) with subtle behavioral differences, undocumented quirks, and version-gated features. Without a shared reference, each wrapper library independently discovers and works around the same issues, leading to divergent implementations and duplicated effort. This repository solves that by providing: 1. **A single, documented contract** for what the FileMaker OData API does and does not support — so every wrapper implements the same behavior instead of guessing. 2. **A version-aware capability matrix** that maps FileMaker Server versions to supported features, query options, and endpoint availability — so wrappers can detect the server version and gate functionality accordingly. 3. **A propagation point for API changes** — when Claris releases a new FileMaker Server version, the update happens here first, then flows to every derived library. 4. **Three explicit categories of coverage**: - **Standard OData features** that FileMaker covers. - **Standard OData features** that FileMaker explicitly does *not* cover (so wrappers don't try to implement them). - **Non-OData additions** specific to FileMaker (containers, scripts, webhooks, custom `Prefer` headers, metadata annotations, system tables, etc.). ### Current downstream implementations [](#current-downstream-implementations) Five projects already consume this spec: ProjectTypeRepository**fms-odata-js**JavaScript/TypeScript client library**fms-odata-py**Python client library**fms-odata-php**PHP client library**fms-odata-mcp**MCP server for AI agents (TypeScript)**fms-odata-webhooks**Webhook handler for FileMaker OData eventsWhat's in this repo ------------------- [](#whats-in-this-repo) ### Specification documents (`docs/`) [](#specification-documents-docs) The primary deliverable. Read in order — each document builds on the previous: \#DocumentDescription00[Overview](docs/00-overview.md)Scope, purpose, version targeting01[Conformance](docs/01-conformance.md)OData standard coverage matrix — what FMS supports and what it doesn't02[Endpoints](docs/02-endpoints.md)Full endpoint reference (URL patterns, methods, status codes)03[Query Options](docs/03-query-options.md)`$filter`, `$select`, `$orderby`, `$top`, `$skip`, `$expand`, `$count`, `$apply`04[Authentication](docs/04-authentication.md)Basic auth, OAuth Bearer token05[Metadata](docs/05-metadata.md)`$metadata` document, annotations, system tables, version detection06[Scripts](docs/06-scripts.md)Script execution, scopes, parameters, results07[Containers](docs/07-containers.md)Container field binary/base64 upload and download08[Batch](docs/08-batch.md)`$batch` requests, changesets, FMS quirks09[Webhooks](docs/09-webhooks.md)Webhook creation and management10[Schema Modification](docs/10-schema-modification.md)DDL: create/delete tables, fields, indexes11[Non-OData Additions](docs/11-non-odata-additions.md)FileMaker-specific extensions beyond the OData standard12[Version Deltas](docs/12-version-deltas.md)2023 → 2024 → 2025 → 2026 → future, feature comparison matrix13[Quirks](docs/13-quirks.md)Real-world quirks, bugs, and workarounds14[Reconciliation](docs/14-reconciliation.md)Divergence matrix between the two downstream repos### Other contents [](#other-contents) ``` schema/ fms-odata-capabilities.json # Machine-readable capability manifest (version feature matrix) packages/ fms-odata-spec-ts/ # Shared TypeScript types package (@fms-odata/spec-ts on npm) src/ # Endpoint, query, auth, metadata, script, container, batch, # webhook, schema, error, version type definitions fms-odata-spec-py/ # Shared Python types package (fms-odata-spec on PyPI) src/fms_odata_spec/ # Same surface as the TS package, as stdlib dataclasses tests/ # pytest suite fms-odata-spec-php/ # Shared PHP types package (fsans/fms-odata-spec-php on Packagist) src/ # Same surface as the TS package, as readonly DTOs and enums tests/ # PHPUnit suite _research/ # Gitignored: cloned source repos used as input ``` ### Companion type packages [](#companion-type-packages) The spec ships three independent, language-specific type packages that mirror the same API surface. They share no runtime dependency on each other and are versioned/published independently using their respective package managers. PackageLanguageRegistryInstall`@fms-odata/spec-ts`TypeScriptnpm`npm install @fms-odata/spec-ts``fms-odata-spec`PythonPyPI`pip install fms-odata-spec``fsans/fms-odata-spec-php`PHPPackagist`composer require fsans/fms-odata-spec-php`**TypeScript package** (`packages/fms-odata-spec-ts/`): ``` cd packages/fms-odata-spec-ts npm install npm run build # tsc -> dist/ npm run typecheck # tsc --noEmit ``` **Python package** (`packages/fms-odata-spec-py/`): ``` cd packages/fms-odata-spec-py python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -e ".[dev]" pytest # run the test suite python -m build # build sdist + wheel into dist/ ``` **PHP package** (run from the repo root, where the Packagist `composer.json` lives): ``` composer install composer test # PHPUnit (283 tests) composer analyse # PHPStan level max composer check # tests + static analysis ``` The Python and PHP folders are intentionally **not** part of any npm workspace glob; the three package managers are kept fully decoupled. Each package has its own CI workflow scoped to its own path filter (`.github/workflows/py-ci.yml`for Python, `.github/workflows/php-ci.yml` for PHP). Version targeting ----------------- [](#version-targeting) The spec covers these FileMaker Server versions, with deltas documented in [docs/12-version-deltas.md](docs/12-version-deltas.md): VersionCodenameStatusClaris FileMaker 2023v20.xSupportedClaris FileMaker 2024v21.xSupportedClaris FileMaker 2025v22.xSupportedClaris FileMaker 2026v26.xCurrent (primary reference)Future / next—Reserved section for announced changesSource of truth --------------- [](#source-of-truth) The spec is built from: 1. **Official Claris OData API documentation** () — primary source. 2. **Observed behavior** from the downstream wrapper repositories (`fms-odata-mcp`, `fms-odata-js`, `fms-odata-py`, `fms-odata-php`, and `fms-odata-webhooks`) — real-world quirks, workarounds, and undocumented behaviors. Where official docs and observed behavior diverge, both are documented and the discrepancy is noted. How downstream libraries use this --------------------------------- [](#how-downstream-libraries-use-this) - **Read the docs** to understand what the API supports and what it doesn't. - **Import the TypeScript types** from `packages/fms-odata-spec-ts` (`@fms-odata/spec-ts` on npm) for shared type definitions in JS/TS projects. - **Import the Python types** from `packages/fms-odata-spec-py` (`fms-odata-spec` on PyPI) for shared type definitions in Python projects. - **Import the PHP types** from `packages/fms-odata-spec-php` (`fsans/fms-odata-spec-php` on Packagist) for shared type definitions in PHP projects. - **Consume the JSON manifest** (`schema/fms-odata-capabilities.json`) to programmatically check feature availability per FileMaker Server version. - **Follow the reconciliation matrix** (docs/14-reconciliation.md) when aligning divergent implementations. OData protocol version ---------------------- [](#odata-protocol-version) FileMaker Server 2023 (v20.x) implements **OData 4.0**. FileMaker Server 2024 (v21.x) and later implement **partial OData 4.01** at intermediate conformance level, with some exceptions. The URL version segment remains `v4` for all versions. See [docs/01-conformance.md](docs/01-conformance.md) for the full conformance level and feature support matrix. Branching model --------------- [](#branching-model) This repository uses a Git Flow-style workflow: BranchPurpose`main`Stable releases only. Every commit on `main` is a merge from `develop` and is tagged with a version tag (`v1.0.0`, `v1.1.0`, etc.).`develop`Active development. All work lands here first via direct commits or feature branches merged back.**Workflow:** 1. Work on `develop` (or a feature branch off `develop`). 2. When a set of changes is ready for release, merge `develop` into `main`. 3. Tag the merge commit on `main` with an annotated version tag (`vMAJOR.MINOR.PATCH`). 4. Push both branches and the tag to `origin`. **Tagging convention:** - Tags follow semantic versioning: `vMAJOR.MINOR.PATCH` for the spec/TS package, `py-vMAJOR.MINOR.PATCH` for the Python package, and `MAJOR.MINOR.PATCH` (bare, no prefix) for the PHP package. - Tags are annotated (`git tag -a`) with a summary of what changed. - Spec/TS and Python tags are created on `main`. PHP tags are also created on `main` (the root `composer.json` with autoload paths into `packages/fms-odata-spec-php/` is what Packagist reads). - If the `@fms-odata/spec-ts` npm package version changes, the tag version should match the package version. **PHP package publishing (Packagist):** The PHP package source lives in `packages/fms-odata-spec-php/`, but a root-level `composer.json` exists at the repository root with PSR-4 autoload paths pointing into that subdirectory. This is required because Packagist only reads `composer.json` from the repository root (the default branch). To release: 1. Ensure the work is merged to `main` and `develop`. 2. Tag the merge commit on `main`: `git tag -a MAJOR.MINOR.PATCH -m "PHP package MAJOR.MINOR.PATCH — ..."` 3. Push: `git push origin main --tags` 4. On Packagist, the repo URL `https://github.com/fsans/fms-odata-spec` resolves versions from bare `MAJOR.MINOR.PATCH` tags on `main`. **Current tags:** TagPackageDescription`v1.0.0`spec/TSInitial spec: 15 docs, JSON manifest, spec-ts types package`v1.1.0`spec/TSMulti-strategy version detection aligned with fms-odata-mcp`v1.1.1`spec/TSScript result envelope fix + FMS v26 quirks`v1.2.0`spec/TSComplete fm-odata -> fms-odata rename (package, directory, schema, all references)`v2.0.0`spec/TSv2.0.0 spec overhaul (versions 20-26, full endpoint/query/metadata/script/container/batch/webhook/schema/error domains)`py-v0.1.0`PythonInitial Python types package (pre-v2.0.0)`py-v2.0.0`PythonPython types package mirroring spec-ts 2.0.0`py-v2.0.1`PythonPython types package 2.0.1 (DDL and webhook endpoint corrections)`2.0.1`PHPFirst PHP mirror — parity with spec-ts/Py 2.0.1License ------- [](#license) MIT — see [LICENSE](LICENSE). ### Health Score 37 — LowBetter than 81% of packages Maintenance71 Regular maintenance activity Popularity10 Limited adoption so far Community9 Small or concentrated contributor base Maturity48 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Unknown Total 1 Last Release 48d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/e31bd27918523411356f90b32995c9e9287ded42815ab2cc2dc989e60e89bed0?d=identicon)[fsans](/maintainers/fsans) --- Top Contributors [![fsans](https://avatars.githubusercontent.com/u/90167?v=4)](https://github.com/fsans "fsans (49 commits)") ### Code Quality TestsPHPUnit Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/fsans-fms-odata-spec-php/health.svg) ``` [![Health](https://phpackages.com/badges/fsans-fms-odata-spec-php/health.svg)](https://phpackages.com/packages/fsans-fms-odata-spec-php) ``` ### Alternatives [kx1000/kwota-slownie Kwota słownie 1019.9k1](/packages/kx1000-kwota-slownie) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)