sys_ws_definition Table

Table Reference/sys_ws_definition

The sys_ws_definition table stores Scripted REST API service definitions in the Integration module. Each record represents a REST service container that holds multiple resources and their HTTP methods.

What This Table Is

The sys_ws_definition table stores the top-level definitions for Scripted REST API services. Each record represents a REST service container that groups related API resources under a single namespace, complete with authentication requirements, documentation, and access controls. This table serves as the parent container for the actual REST resources defined in sys_ws_operation records.

This table belongs to the Integration module and supports the platform's custom REST API framework. When you create a new Scripted REST API through System Web Services > Scripted REST APIs, you're creating a record in this table. The service definition establishes the API's base path, security model, and serves as the organizational unit for grouping related endpoints.

The table extends sys_metadata and acts as a parent to sys_ws_operation records, which define the actual HTTP methods and resources. The relationship is one-to-many: each service definition can contain multiple operations (GET /users, POST /users, etc.), but each operation belongs to exactly one service definition.

Enterprise instances typically contain 50-200 custom REST service definitions, with record volume remaining low since each represents a service container rather than individual API calls. Query performance is excellent due to low volume, though joining to sys_ws_operation records can become expensive if your service definitions contain hundreds of operations each.

When You'll Script Against This Table

You'll query this table in Script Includes that manage API lifecycle, Business Rules that enforce REST service governance, and Scheduled Scripts that audit or report on custom API usage. Integration developers commonly script against it when building API management dashboards, automated API documentation generators, or when implementing custom authentication flows that need to validate service definitions.

Access requires the rest_service_admin role for full CRUD operations, though web_service_admin provides read access. The table respects application scoping - global scope can see all records, while scoped applications only see their own service definitions unless explicitly granted cross-scope access.

Common scripting patterns:

Query active service definitions to build API inventory reports
Check service authentication requirements before processing API requests
Validate base path uniqueness when creating new service definitions programmatically
Join with sys_ws_operation to count endpoints per service for governance reporting
Update service documentation or version numbers through automated deployment scripts
Implement custom service lifecycle workflows that transition services between development and production states
Generate OpenAPI/Swagger documentation from service and operation metadata

Table Gotchas

⚠️

The base_path field must be unique across all active service definitions, but ServiceNow allows duplicate paths if one service is inactive. This can cause deployment issues when reactivating services.

⚠️

Authentication configuration in the authentication_type field only sets the service-level default. Individual operations can override this, making service-level queries for auth requirements incomplete.

The namespace field becomes part of the REST endpoint URL structure, but changing it after operations exist doesn't update the actual endpoint URLs until you republish the service
Service definitions in inactive applications (sys_scope.active=false) remain visible in this table but their endpoints return 404 errors
The doc_link field stores relative paths, but the platform doesn't validate that the documentation actually exists at that location

⚠️

Deleting a service definition cascades to all child sys_ws_operation records without warning, immediately breaking all endpoints for that service.

Version field is free-text and not enforced - you can have multiple services claiming to be version "1.0" with completely different implementations

Free Newsletter

Enjoying this? Get one deep-dive per week.

Join 1,000+ ServiceNow pros — scripts, GlideRecord patterns, Flow Designer techniques, and career moves. Free.

This table extends sys_metadata, inheriting application scoping and update set tracking capabilities. The parent relationship means service definitions participate in application lifecycle management and can be deployed between instances as part of scoped applications.

The primary child relationship is with sys_ws_operation, where each operation record defines a specific HTTP method and resource path within the service. Developers frequently join these tables to build complete API inventories or to validate that services have the expected operations defined. The sys_scope table provides the application context, essential for understanding which team owns each service and whether it's available in the current instance configuration.

Integration monitoring often requires joining with syslog_transaction to correlate service definitions with actual API usage patterns and performance metrics. The sys_user table becomes relevant when implementing custom authentication or authorization logic that needs to validate API consumers against service-level access controls.

Chrome Extension

Sourdough: ServiceNow Monitoring and Analytics

A Chrome extension for ServiceNow Admins and Developers with essential tools, analytics, graphs and monitoring features.

Instance HealthGraphs & ChartsAPI HealthDeveloper ToolsQuick SearchInstance Switcher

Add to Chrome

Free to install. Pro $5/month after a 14-day no-card trial.
Pro requires the ServiceNow admin role. Upgrade inside the extension.

Overview

Tasks

CMDB

API

Metrics

Monitor

Internals

Instance:sourdoughdev·Version:Yokohama

Instance StateONLINE

System StatusFully Operational

Session Timeout90 minutes

Logged-In Sessions2 (20 active)

Build Nameyokohama-12-18-2024_p1

IP Address10.159.128.43

Instance HealthHealth Score: 90%

🔥 5dSourdough (Chrome Plugin)Dark Mode

Key Fields

Column	Type	Label	Notes
name	string	Name	Display name for the REST service. Must be unique within the application scope and becomes part of the service's identity in API documentation.
namespace	string	API Namespace	URL namespace that groups related services. Forms part of the endpoint URL structure and should follow RESTful naming conventions.
base_path	string	Base API Path	The root path for all operations in this service. Must be unique across active services and starts with a forward slash.
active	boolean	Active	Controls whether the service endpoints are accessible. Inactive services return 404 errors but remain visible in the platform UI.
authentication_type	choice	Authentication Type	Default authentication method for operations in this service. Individual operations can override this setting, making service-level queries incomplete.
short_description	string	Short Description	Brief description of the service's purpose. Appears in API documentation and service catalogs, so keep it business-friendly.
version	string	Version	Free-text version identifier with no enforcement. Multiple services can claim the same version number with different implementations.
doc_link	string	Documentation Link	Relative path to service documentation. The platform doesn't validate that documentation exists at this location.
enforce_acl	boolean	Enforce ACL	Whether to apply Access Control List rules to service operations. Critical for security but can impact performance on high-volume APIs.
consumes	string	Consumes	Comma-separated list of MIME types this service can consume. Defaults to application/json but operations can override this.
produces	string	Produces	Comma-separated list of MIME types this service can produce. Individual operations inherit this but can specify their own response types.
sys_scope	reference	Application	References the application scope that owns this service. Critical for determining visibility and deployment boundaries across instances.
web_service_definition	reference	Web Service Definition	Optional reference to related WSDL-based web service definitions. Rarely used in modern REST implementations but maintained for compatibility.
service_id	string	Service ID	Internal identifier used by the REST framework. Auto-generated and should not be modified manually as it affects endpoint routing.
relative_path	string	Relative Path	Computed field combining namespace and base_path. Read-only and used internally for URL routing and endpoint resolution.

Common Queries

Get all active REST service definitions

// Most basic query - what developers try first
var gr = new GlideRecord('sys_ws_definition');
gr.addQuery('active', true);
gr.query();

while (gr.next()) {
    // Process active services
    gs.info('Service: ' + gr.getValue('name') + 
           ' Path: ' + gr.getValue('base_path'));
}

// Returns all services currently accepting requests
// Check application scope if you only want specific apps

Find services by authentication type and application scope

// Real-world security audit scenario
var gr = new GlideRecord('sys_ws_definition');
gr.addQuery('active', true);
gr.addQuery('authentication_type', 'oauth2');
gr.addQuery('sys_scope.name', 'LIKE', 'x_custom_%');
gr.query();

var count = 0;
while (gr.next()) {
    count++;
    gs.info('OAuth2 Service: ' + gr.getDisplayValue('name') + 
           ' in ' + gr.getDisplayValue('sys_scope'));
}

gs.info('Found ' + count + ' custom OAuth2 services');

Get services with their operation counts for API governance

// Business scenario: API sprawl assessment
var gr = new GlideRecord('sys_ws_definition');
gr.addQuery('active', true);
gr.query();

while (gr.next()) {
    // Count operations per service
    var opGr = new GlideRecord('sys_ws_operation');
    opGr.addQuery('web_service_definition', gr.getValue('sys_id'));
    opGr.addQuery('active', true);
    opGr.query();
    
    gs.info('Service: ' + gr.getValue('name') + 
           ' has ' + opGr.getRowCount() + ' operations');
}

Count services by application using GlideAggregate

// Aggregate count for reporting dashboard
var ga = new GlideAggregate('sys_ws_definition');
ga.addQuery('active', true);
ga.addAggregate('COUNT');
ga.groupBy('sys_scope');
ga.query();

while (ga.next()) {
    var appId = ga.getValue('sys_scope');
    var count = ga.getAggregate('COUNT');
    
    var appGr = new GlideRecord('sys_scope');
    if (appGr.get(appId)) {
        gs.info('App: ' + appGr.getValue('name') + 
               ' Services: ' + count);
    }
}

Wrong way vs right way to check for duplicate base paths

// WRONG: This misses inactive services that could conflict
var wrong = new GlideRecord('sys_ws_definition');
wrong.addQuery('base_path', '/api/users');
wrong.addQuery('active', true);
var hasDuplicate = wrong.hasNext();

// RIGHT: Check all services regardless of active state
var right = new GlideRecord('sys_ws_definition');
right.addQuery('base_path', '/api/users');
right.query();
// Inactive services can be reactivated, causing conflicts
if (right.getRowCount() > 0) {
    gs.warn('Base path conflict detected - check inactive services too');
}

Related Tables

sys_user

Test Your Knowledge

Quick 3-question quiz — see how your ServiceNow skills stack up.

Question 1 of 3Performance

A list view on a table with millions of records is slow. Best fix?

Select an answer to continue