Orgs — serializers

Responsibilities

The orgs serializers define the API contract for organizational data, memberships, and customer links.

They are responsible for:

• validating incoming organization and membership payloads
• shaping organization, branding, membership, and customer-link responses
• exposing derived read-only helpers useful to frontend clients
• keeping view code thin and consistent

They are not responsible for:

• role-management business rules
• membership lifecycle logic
• organization update workflows
• customer-link activation/deactivation rules

Those behaviors belong in the service layer.

---

Main serializers

serializers.organizations.OrganizationListSerializer

Lightweight serializer for organizations visible to the current user.

• Fields
• id
• name
• slug
• parent
• org_type
• display_name_effective
• role
• Derived fields
• display_name_effective
• role
• Validation
• none beyond standard model field serialization
• Used by
• MyOrgsView

Notes

role is calculated for the requesting user using active OrgMembership rows. This is mainly a frontend convenience field for org-switching and startup flows.

---

serializers.organizations.OrganizationDetailSerializer

Full serializer for current organization details and editable org configuration.

• Fields
• Core identity
  • id
  • name
  • slug
  • org_type
  • parent
  • is_active
  • created_at
  • settings
• Branding / legal identity
  • legal_name
  • display_name
  • display_name_effective
• Address / contact
  • address_line1
  • address_line2
  • postal_code
  • city
  • state_region
  • country
  • address_single_line
  • phone
  • email
  • website
• Legal / registration
  • vat_number
  • coc_number
• Assets / colors
  • logo
  • logo_pdf
  • brand_primary
  • brand_text
  • brand_muted
• PDF options
  • pdf_footer_note
  • pdf_show_legal_ids
  • pdf_show_contact_details
• Read-only fields
• id
• slug
• created_at
• display_name_effective
• address_single_line
• Validation
• trims most text fields
• lowercases and trims email
• normalizes branding and document fields
• Used by
• CurrentOrgDetailView
• CurrentOrgUpdateView

Notes

This serializer exposes the editable organization record while also returning useful derived read-only helpers.

---

serializers.organizations.OrganizationBrandingSerializer

Serializer focused specifically on branding and document identity fields.

• Fields
• id
• name
• slug
• display_name
• display_name_effective
• legal_name
• address_line1
• address_line2
• postal_code
• city
• state_region
• country
• address_single_line
• phone
• email
• website
• vat_number
• coc_number
• logo
• logo_pdf
• brand_primary
• brand_text
• brand_muted
• pdf_footer_note
• pdf_show_legal_ids
• pdf_show_contact_details
• effective_branding
• Read-only fields
• id
• name
• slug
• display_name_effective
• address_single_line
• effective_branding
• Derived fields
• display_name_effective
• address_single_line
• effective_branding
• Used by
• CurrentOrgBrandingView
• CurrentOrgBrandingUpdateView

Notes

This serializer is useful when the frontend wants a dedicated org-branding/settings screen or a branding preview payload.

---

serializers.memberships.OrgMemberListSerializer

Lightweight member-list serializer for current org member views.

• Fields
• id (mapped from user_id)
• label
• email
• role
• is_active
• joined_at
• Derived fields
• label
• Used by
• CurrentOrgMembersView

Label resolution behavior

The serializer resolves the user label in this order: 1. user.profile.display_name 2. user.get_full_name() 3. user.email 4. user.username 5. fallback "User <id>"

This keeps member lists frontend-friendly without forcing extra lookups.

---

serializers.memberships.OrgMembershipSerializer

Full serializer for one internal org membership.

• Fields
• id
• user_id
• user_username
• user_email
• user_label
• org
• role
• is_active
• joined_at
• Read-only fields
• id
• user_id
• user_username
• user_email
• user_label
• joined_at
• Derived fields
• user_label
• Used by
• membership role update response
• membership deactivate response
• membership reactivate response

Notes

This serializer is the fuller version of membership output used after state-changing operations.

---

serializers.memberships.OrgMembershipRoleUpdateSerializer

Input serializer for changing a member role.

• Fields
• role
• Validation
• validates against OrgMembership.Role.choices
• strips the incoming string
• Used by
• OrgMembershipRoleUpdateView

Notes

The serializer only validates the role payload shape. Actual permission checks and lifecycle rules are handled in services.membership.

---

serializers.memberships.OrgMembershipStatusSerializer

Minimal serializer for membership activation/deactivation payloads.

• Fields
• is_active
• Validation
• standard boolean validation
• Used by
• currently optional / reserved for future status endpoints

Notes

This serializer is useful if you later expose a generic status patch endpoint instead of separate activate/deactivate actions.

---

serializers.customers.CustomerLinkSerializer

Serializer for internal-org ↔ customer-org links.

• Fields
• id
• internal_org
• internal_org_name
• customer_org
• customer_org_name
• customer_org_slug
• is_active
• created_at
• Read-only fields
• id
• created_at
• Derived fields
• internal_org_name
• customer_org_name
• customer_org_slug
• Used by
• CurrentOrgCustomerLinksView

Notes

This serializer is list-friendly and makes customer links easy to display in internal org administration UIs.

---

serializers.customers.CustomerMembershipSerializer

Serializer for members of a customer organization.

• Fields
• id
• user_id
• user_email
• customer_org
• customer_org_name
• role
• is_active
• joined_at
• Read-only fields
• id
• user_id
• user_email
• customer_org_name
• joined_at
• Derived fields
• customer_org_name
• Used by
• CurrentCustomerOrgMembersView

Notes

This serializer gives internal staff visibility into who belongs to a linked customer org.

---

Serializer relationship overview

flowchart TD
    OrganizationListSerializer --> Organization["Organization"]
    OrganizationDetailSerializer --> Organization
    OrganizationBrandingSerializer --> Organization

    OrgMemberListSerializer --> OrgMembership["OrgMembership"]
    OrgMembershipSerializer --> OrgMembership
    OrgMembershipRoleUpdateSerializer --> OrgMembership
    OrgMembershipStatusSerializer --> OrgMembership

    CustomerLinkSerializer --> CustomerLink["CustomerLink"]
    CustomerMembershipSerializer --> CustomerMembership["CustomerMembership"]

Read vs write split

The serializer layer in orgs follows a mostly clear read/write separation:

Read-focused serializers • OrganizationListSerializer • OrganizationDetailSerializer • OrganizationBrandingSerializer • OrgMemberListSerializer • OrgMembershipSerializer • CustomerLinkSerializer • CustomerMembershipSerializer

Write/input-focused serializers • OrgMembershipRoleUpdateSerializer • OrgMembershipStatusSerializer

This helps keep update payloads small and stable while still returning rich read models.

Design notes

Why role is exposed on organization list rows

OrganizationListSerializer includes the current user’s role for each org to make org-selection and frontend gating easier.

This is intentionally a convenience field and not a replacement for backend authorization checks.

Why there are separate membership serializers

There are two different needs: • list current org members in a compact way • return full membership details after a membership update

That is why the app uses: • OrgMemberListSerializer for member listings • OrgMembershipSerializer for mutation responses

This keeps list payloads smaller while preserving detail where needed.

---

Why branding has a dedicated serializer

Branding/document identity is important enough in this system to justify its own serializer.

It supports: • branding settings screens • PDF/report previews • consistent resolved branding payloads across parent/child org structures

---

Likely future additions

As the orgs app expands, likely serializer additions include: • organization create serializer • organization hierarchy/tree serializer • customer-link write serializer • membership create/add serializer • ownership transfer serializer • org summary serializer for dashboards

The current serializer split already gives a clean base for that growth.