namespace vs interface

[artsiommiksiuk]

I think I'm getting confused over and over with namespaces vs interface for grouping operations. From the documentation you can use both, but in contrast with TS, there's no declaration merging, and e.g. using namespaces to declare inner models gives a default warning of

No namespace with '@service' was found, but Namespace 'OrganizationIdentitiesIndex' contains routes. Did you mean to annotate this with '@service'

On the other hand, interface can't have inner models definitions, so it's not an equivalent option.

Additionally, implementing custom emitter becoming trickier because both namespace and interfaces can be used for "service" definitions, which raises a basic conceptual question: which one to use for which cases? Or what's an intention for both of them.

I read documentation on namespace and interfaces in typespec, I'm fluent with TypeScript and things, but conceptually feels like either namespaces or interfaces aligned poorly in their purposes.

Can somebody please explain the intended use cases for both, besides "namespaces as in C# namespace for grouping and interfaces are classical interfaces", because even this is not completely true for TypeSpec. Like practically, what's to use when.

[artsiommiksiuk]

To be more specific, this is the way I'm sometimes encapsulating data models into namespaces, because they make no sense in global context otherwise. In this case I have to have this additional #suppress statement, which seems a bit off for this use case, and also suggests that namespaces are not intended to be used like this.

#suppress "@typespec/http/no-service-found" ""
@tag("index")
@route("/organizations/{organizationId}/index/identities")
@useAuth(BearerAuth)
namespace OrganizationIdentitiesIndex {
    model Record {
        organization: PickProperties<Organization, "id" | "name">;
        identity: PickProperties<Identity, "id" | "name" | "avatarUrl">;
        authzAttrs: OmitProperties<
            MyAPI.Authz.OrganizationIdentityAttributes,
            "kind" | "organizationId" | "identityId"
        >;
    }

    @get
    op query(
        @path organizationId: string,
        ...QueryPageParameters,
    ): QueryPage<Record>;
}

[timotheeguerin]

Namespace are just grouping element that will be merged across file with the same namespaces(as your comment said its quite similar to C# and there isn't much more to that).
Interface are just a reusable group of operations. So indeed they cannot have anything else that operation. We did talk at some point of having a type that could contain properties like TypeScript interface but we haven't had a real need for it yet.

What maybe you are getting confused by is that the openapi3 emitter will do a special treatment of the global namespace when you don't have a service defined. It will count anything directly at the root as part of this service. However if you want to include more then you need to make your own root namespace with @service

@service
@tag("index")
@route("/organizations/{organizationId}/index/identities")
@useAuth(BearerAuth)
namespace OrganizationIdentitiesIndex {
    model Record {
        organization: PickProperties<Organization, "id" | "name">;
        identity: PickProperties<Identity, "id" | "name" | "avatarUrl">;
        authzAttrs: OmitProperties<
            MyAPI.Authz.OrganizationIdentityAttributes,
            "kind" | "organizationId" | "identityId"
        >;
    }

    @get
    op query(
        @path organizationId: string,
        ...QueryPageParameters,
    ): QueryPage<Record>;
}

or this way and you can add multiple sub grouping

@service
namespace MyService;

@tag("index")
@route("/organizations/{organizationId}/index/identities")
@useAuth(BearerAuth)
namespace OrganizationIdentitiesIndex {
    model Record {
        organization: PickProperties<Organization, "id" | "name">;
        identity: PickProperties<Identity, "id" | "name" | "avatarUrl">;
        authzAttrs: OmitProperties<
            MyAPI.Authz.OrganizationIdentityAttributes,
            "kind" | "organizationId" | "identityId"
        >;
    }

    @get
    op query(
        @path organizationId: string,
        ...QueryPageParameters,
    ): QueryPage<Record>;
}

[artsiommiksiuk]

Well, this case is actually not a root namespace. To complete example, it is actually:

import "@typespec/http";
// other imports...

using Http;

namespace MyAPI.Index;

#suppress "@typespec/http/no-service-found" ""
@tag("index")
@route("/organizations/{organizationId}/index/identities")
@useAuth(BearerAuth)
namespace OrganizationIdentitiesIndex {
    model Record {
        organization: PickProperties<Organization, "id" | "name">;
        identity: PickProperties<Identity, "id" | "name" | "avatarUrl">;
        authzAttrs: OmitProperties<
            MyAPI.Authz.OrganizationIdentityAttributes,
            "kind" | "organizationId" | "identityId"
        >;
    }

    @get
    op query(
        @path organizationId: string,
        ...QueryPageParameters,
    ): QueryPage<Record>;
}

Root namespace declared just in main.tsp.

As far as I understood, typespec with namespaces is C# and not typescript approach, which has a consequences for emitters that modules boundaries are now on namespaces, and not files. If understood this right. It sure looks like so.

If it is, this needs to be added into documentation, because this might be very confusing for js devs, as this is a non standard for js world way to do modules.

I think I understand why, like relative to keeping exports and starting again explicitly exporting things, but still wish it was better documented - the conceptual approach for modules.

[artsiommiksiuk]

And yeah, why interface doesn't require @service decorator, but namespaces does in this case? That's also somehow non consistent.

What would be the difference between defining

@service
@server("/api/a")
namespace A;

and

@route("/api/a")
interface A;

?

I mean, I understand the OAS semantics for this, but the way oas emitter maps it - I'm not sure.

[artsiommiksiuk]

Ah, and also I figured, that

No namespace with '@service' was found, but Namespace 'Self' contains routes. Did you mean to annotate this with '@service'?

When the file is not yet included into main. Seems like in this case it thinks this namespace must be a root one. Making import of the current file into the main root solves this warning.

[timotheeguerin]

Yeah interface doesn't. The closer equivalence would be an interface is a class and operation are functions while namespace are modules.

The reason why it just works for interface and operation without a namespace is half of a legacy feature half very useful for making repros without adding extra code. Defining code in the global namespace can result in some very confusing bugs. And realistically anytime you will actually describe your service you will need to group it into a namespace to be able able to decoratte other things like authentication, servers, etc.
The general guideline is everything your spec or library should be in a namespace of the form MyCompany.MyProduct (Or whatever other sturcture you choose). Becausse namespace merge across files, libraries it is important to make sure you will not conflict with something else.