[arinthros]

Why

OrganizationsClient.getOrganization throws a validation error for every organization the live API returns. The API sends address: null when an organization has no address, and description: null for some, but OrganizationSchema only allowed those fields to be omitted. useOrganizations drops failed queries, so BibleVersionPicker has not shown publisher names since they shipped in 2.2.0.

Jira: YPE-6399. Spec follow-up: YPE-6438

Sampled against production on 2026-10-29: the organization_id of every version from getVersions for en, es, fr, pt, de, ko (11 unique organizations).

Field	Null in sample	Schema before
address	11/11	optional, not nullable
description	3/11	optional, not nullable
phone, parent_organization_id	11/11	already nullable
email	4/11	already nullable

getOrganization threw on 11/11.

What changed

• description and address in OrganizationSchema accept null.
• Core organization mocks now mirror the live response, including the null fields. They used to leave those fields out, so tests never sent a null.
• Added cases for a null address and a null description, and a schema test that only those two fields accept null (name and website_url still reject it).
• UI organization mocks (packages/ui/src/test/mock-data/organizations.json) now match the live shape too, with the null fields.
• New PublisherNames story (integration) checks that "Biblica" shows in the version picker.

Scope

• Only the two fields seen as null in live responses. name, primary_language, and website_url were never null in the sample, so they stay as they are.
• The fields of a present address object are unchanged; no sampled organization had one.

Tradeoffs

The SDK matched the published spec, which declares description and address without nullable: true. This PR follows the API's actual behavior. YPE-6438 tracks fixing the spec (or having the API omit the fields). The spec's source is GitLab apis/platform/transformers spec/schemas/organization.yaml; its sync_portal_artifacts job copies it to the developer hub's devdocs/apis/schemas/organization.yaml, so the fix belongs in transformers. The Portal hit the same pattern in YPE-5767.

Blast Radius

Organization['description'] and Organization['address'] widen to include null. Nothing in hooks or ui reads either field. A host that reads them with strict null checks may need a null check, but those reads could not have succeeded before, since every response failed to parse. The changeset calls out the type change.

Verification

• Before the fix, the existing Lockman test and both new tests failed with invalid_type on address and description. After the fix they pass.
• PublisherNames story: fails with the old schema ("Unable to find an element with the text: Biblica"), passes with the fix.
• After merging main: pnpm exec turbo test for core, hooks, and ui: 345 (2 skipped), 200, and 542 passed.
• vitest run --project storybook: 69 of 70 passed locally. Navigate And Focus in bible-reader-search.stories.tsx fails the same way without this PR's changes.
• pnpm build, pnpm lint, and pnpm exec turbo typecheck --force pass.

Test plan

• new OrganizationsClient(apiClient).getOrganization('05a9aa40-37b6-4e34-b9f1-a443fa4b1fff') (Biblica) against production resolves with address: null.
• Open BibleVersionPicker in the Vite example. Publisher names show above version titles (e.g. Biblica above NIV).

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; no actionable defects remain.

Summary

Allows OrganizationSchema to accept null address and description values without changing the other fields.

• Organization lookups accept null address and description fields.

_{Reviews (4) · Last reviewed commit: "Merge remote-tracking branch 'origin/mai..." · Reviewed by Greptile}

[changeset-bot]

🦋 Changeset detected

Latest commit: d44ac04

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@youversion/platform-core	Patch
@youversion/platform-react-hooks	Patch
@youversion/platform-react-ui	Patch
vite-react	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[camrun91]

Thanks, @arinthros! The schema fix is correct, and the CI is green. I have some required changes before I can approve. Most are small. I put 4 inline comments on the diff. The items below are in files that are not in the diff.

1. Required: test the UI path with null fields
packages/ui/src/test/mock-data/organizations.json
The UI mock does not have address or description. Thus the UI tests do not see the null values that caused the bug. Also, no story checks that "Biblica" shows in the version picker (docs/testing.md: "Account for what their mocks bypass" and "Prefer E2E").
Please give the mock the live shape, with the null fields. Then add an integration story with a play check that "Biblica" shows.

2. Required: update the branch
The branch is behind main. Please merge or rebase main, then make sure the CI is green. I did a local merge, and it was clean. All tests passed.

When these items are done, I can approve. Thank you!

[camrun91]

@arinthros reviewed and commented. Feel free to push back on anything that you think deserves the push back.

[arinthros]

Thanks @camrun91, all addressed:

• UI path with null fields: packages/ui/src/test/mock-data/organizations.json now matches the live shape (null address, email, phone, parent_organization_id, and a null description for Cambridge). New PublisherNames story, tagged integration, opens the picker and checks that "Biblica" shows on the NIV row. With the old schema it fails ("Unable to find an element with the text: Biblica"); with the fix it passes. (0a9434e)
• Branch update: merged main (3708076), clean.
• Inline items: replied on each thread.

Locally, core, hooks, and ui tests pass (345, 200, 542), plus build, lint, and typecheck. In the Storybook project, 69 of 70 pass; Navigate And Focus in bible-reader-search.stories.tsx fails the same way without these changes.