Field projections

Use fields to request only the response properties you need. Projected result types make omitted properties explicit. Leave out fields to receive the ordinary model.

These examples assume you have a configured sdk from Getting started.

JavaScript and TypeScript

Pass a field string to an sdk.api GET method that supports fields:

Quick start 

import { type Company, type Projected } from '@solibo/solibo-sdk'

const company: Projected<Company> = await sdk.api.companies.showCompany({
  companyId,
  fields: 'id,orgNr',
})

if (company.orgNr === undefined) {
  console.log('orgNr was omitted')
} else if (company.orgNr === null) {
  console.log('orgNr has no value')
} else {
  console.log(company.orgNr)
}

With an inline field string, the projected type is inferred; the annotation above is optional. Projected<T> makes properties optional and readonly, including nested properties. It does not infer an exact object type from the names in your selector.

The TypeScript client appends each model’s required fields to your fields selector so that the response can be decoded; expect them in the result. Kotlin and plain HTTP send exactly what you ask for.

Omitted values and selected nulls

undefined means the property was omitted. null means it was returned with a null value. Use value ?? fallback when you want to handle both the same way.

Collection responses

Standard pages keep items, meta, and paging; only each item’s properties become optional. Direct-array endpoints return arrays of projected items. Other response wrappers keep their own shape, with optional properties.

Nested selectors

Use syntax such as fields: 'id,children(id,classification)' to select nested properties. Nested results are optional too.

Dynamic field strings

Prefer inline selectors or constants declared with as const. A selector typed as plain string may infer the full response type; explicitly treat that result as Projected<T>.

Polymorphic results

For residents, branch on resident.type to access subtype properties; the discriminator is always included.

TanStack Query and React

Pass fields to queries and hooks in the same way. It is included in their query keys so different selections are cached separately. Result-type precision varies by wrapper; use sdk.api when you need direct projection inference.

Raw KMP interop

sdk.raw does not apply these TypeScript projection types. Prefer sdk.api for projected responses.

Kotlin

Pass ProjectionFields and import the operation’s projection extension:

Quick start 

import no.solibo.oss.sdk.api.projection.ProjectionField
import no.solibo.oss.sdk.api.projection.ProjectionFields
import no.solibo.oss.sdk.api.projection.showCompany

val company = sdk.api.companies.showCompany(
    companyId = companyId,
    fields = ProjectionFields("id,orgNr"),
).body()

when (val orgNr = company.orgNr) {
    ProjectionField.Absent -> println("orgNr was omitted")
    is ProjectionField.Present -> println(orgNr.value)
}

The result is ProjectedCompany. Both the extension import and ProjectionFields are required to select the projected response type.

Reading projected properties

  • ProjectionField.Absent: the property was omitted.
  • ProjectionField.Present(value): the property was returned, possibly with a nullable value.

Import getOrNull from the same package for a fallback-friendly read such as company.orgNr.getOrNull(). It returns null for both an absent property and a selected null. Use when when you need to distinguish them. Non-nullable properties still reject a selected null.

Nested objects are projected too. For example, ProjectionFields("id,children(id,classification)") selects fields on each child; those child properties are also ProjectionField values.

Projected response shapes

Response Projected result
Standard page ProjectedPage<ProjectedT>; meta and paging stay unchanged
Direct array List<ProjectedT>
Other collection wrapper Projected wrapper, including its items property
Supported detail A model such as ProjectedCompany

Sealed response models

Include the discriminator when selecting polymorphic models, for example ProjectionFields("type,id,name") for residents. You can then branch on projected subtypes such as ProjectedPersonResident and ProjectedOrganizationResident.

Which Kotlin operations are supported?

Typed overloads cover JSON GET endpoints with fields that return a standard page, a direct array, or an object with an array-valued items property. Detail overloads are available for showCompany, showPerson, and showOrganization.

Kotlin compatibility path

Passing a plain string selects the original method and its full model type. Prefer ProjectionFields where supported: a full model may fail to deserialize when required properties are omitted.

Solibo AS